@geolonia/geonicdb-sdk 0.11.1 → 0.12.0

package/README.md

@@ -558,6 +558,55 @@ try {
 | `RateLimitError` | 429 | Rate limited (`retryAfter` property) |
 | `NetworkError` | — | Fetch failure, DNS error, timeout |
 
+## React Hooks (`@geolonia/geonicdb-sdk/react`)
+
+Optional React integration, shipped as a separate subpath so the core SDK stays
+framework-agnostic. Requires React 18 or 19 (declared as an **optional peer
+dependency** — core consumers are unaffected).
+
+```tsx
+import GeonicDB from '@geolonia/geonicdb-sdk';
+import { useLdEntities, useTemporalData, GeonicDbMap } from '@geolonia/geonicdb-sdk/react';
+
+const db = new GeonicDB({ baseUrl, tenant });
+
+function Rooms() {
+  const { entities, loading, error, refetch } = useLdEntities(db, { type: 'Room', limit: 100 });
+  if (loading) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <GeonicDbMap entities={entities} apiKey="YOUR-GEOLONIA-KEY" />;
+}
+```
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `useLdEntities(client, options?)` | hook | NGSI-LD エンティティ取得。`{ entities, loading, error, refetch }` を返す。`options`: `type` / `limit` / `attrs` / `q` / `scopeQ` |
+| `useTemporalData(client, options)` | hook | Temporal API 取得。`{ data, loading, error, refetch }` を返す。`options.id` 指定時は単一エンティティ、`options.enabled === false` で取得スキップ |
+| `GeonicDbMap` | component | Geolonia 地図にエンティティをマーカー描画。`@geolonia/embed`（optional peer）を動的 import |
+
+両 hook は in-flight リクエストを世代管理しており、`options` 変更やアンマウント時に古いレスポンスが新しい結果を上書きしない。`GeonicDbMap` のポップアップは `entity.id` / `entity.type` を HTML エスケープして描画する。
+
+## NGSIv2 Client (`@geolonia/geonicdb-sdk/ngsi-v2`)
+
+NGSIv2 (`/v2/entities`) を叩く軽量クライアント。NGSI-LD を使うコア SDK とは独立した
+サブパスで、NGSIv2 のみを使う利用者向け。
+
+```ts
+import { createNgsiV2Client } from '@geolonia/geonicdb-sdk/ngsi-v2';
+
+const client = createNgsiV2Client({ baseUrl: 'https://geonicdb.example.com', apiKey: 'KEY', service: 'mytenant' });
+const rooms = await client.getEntities({ type: 'Room', limit: 20 });
+```
+
+| Method | Description |
+|--------|-------------|
+| `createNgsiV2Client(config)` | `NgsiV2Client` を生成。`config`: `baseUrl`（必須）/ `apiKey` / `service` |
+| `getEntities(options?)` | エンティティ一覧（`type` / `q` / `limit` / `offset` / `attrs` / `options`） |
+| `getEntity(id, options?)` | 単一エンティティ取得 |
+| `createEntity(entity)` | エンティティ作成 |
+| `updateEntityAttributes(id, attrs)` | 属性の部分更新 |
+| `deleteEntity(id)` | エンティティ削除 |
+
 ## License
 
 MIT

package/ngsi-v2/index.cjs

@@ -0,0 +1,92 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/sdk/ngsi-v2/index.ts
+var index_exports = {};
+__export(index_exports, {
+  NgsiV2Client: () => NgsiV2Client,
+  createNgsiV2Client: () => createNgsiV2Client
+});
+module.exports = __toCommonJS(index_exports);
+var NgsiV2Client = class {
+  constructor(config) {
+    __publicField(this, "baseUrl");
+    __publicField(this, "headers");
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (config.service) this.headers["Fiware-Service"] = config.service;
+    if (config.servicePath) this.headers["Fiware-ServicePath"] = config.servicePath;
+  }
+  async request(method, path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: this.headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ error: `HTTP ${res.status}` }));
+      const description = typeof err["description"] === "string" ? err["description"] : void 0;
+      const error = typeof err["error"] === "string" ? err["error"] : void 0;
+      throw new Error(description ?? error ?? `HTTP ${res.status}`);
+    }
+    if (res.status === 201 || res.status === 204) return void 0;
+    return res.json();
+  }
+  /** List entities */
+  async getEntities(options) {
+    const sp = new URLSearchParams();
+    if (options?.type) sp.set("type", options.type);
+    if (options?.q) sp.set("q", options.q);
+    if (options?.limit !== void 0) sp.set("limit", String(options.limit));
+    if (options?.offset !== void 0) sp.set("offset", String(options.offset));
+    if (options?.attrs) sp.set("attrs", options.attrs);
+    if (options?.options) sp.set("options", options.options);
+    const qs = sp.toString();
+    return this.request("GET", `/v2/entities${qs ? "?" + qs : ""}`);
+  }
+  /** Get single entity by ID */
+  async getEntity(entityId, options) {
+    const sp = new URLSearchParams();
+    if (options?.attrs) sp.set("attrs", options.attrs);
+    if (options?.options) sp.set("options", options.options);
+    const qs = sp.toString();
+    return this.request("GET", `/v2/entities/${encodeURIComponent(entityId)}${qs ? "?" + qs : ""}`);
+  }
+  /** Create entity */
+  async createEntity(entity) {
+    await this.request("POST", "/v2/entities", entity);
+  }
+  /** Update entity attributes (partial) */
+  async updateEntityAttributes(entityId, attrs) {
+    await this.request("PATCH", `/v2/entities/${encodeURIComponent(entityId)}/attrs`, attrs);
+  }
+  /** Delete entity */
+  async deleteEntity(entityId) {
+    await this.request("DELETE", `/v2/entities/${encodeURIComponent(entityId)}`);
+  }
+};
+function createNgsiV2Client(config) {
+  return new NgsiV2Client(config);
+}
+//# sourceMappingURL=index.cjs.map

package/ngsi-v2/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/sdk/ngsi-v2/index.ts"],
+  "sourcesContent": ["// SPDX-License-Identifier: MIT\n// Copyright (c) 2026 Geolonia Inc.\n// See LICENSE in src/sdk/ for full license text.\n\n/**\n * NGSIv2 basic client \u2014 bundled per ADR\u8AD6\u70B92=a (\u6BBF\u88C1\u53EF\u78BA\u5B9A)\n *\n * Scope: basic entity CRUD only. No subscriptions, no batch ops.\n * For NGSI-LD, use the core GeonicDB client instead.\n */\n\nexport interface NgsiV2ClientConfig {\n  baseUrl: string;\n  /** FIWARE service (tenant) */\n  service?: string;\n  /** FIWARE service path */\n  servicePath?: string;\n}\n\nexport interface NgsiV2Entity {\n  id: string;\n  type: string;\n  [key: string]: string | NgsiV2Attribute | undefined;\n}\n\nexport interface NgsiV2Attribute {\n  type: string;\n  value: string | number | boolean | object | null;\n  metadata?: Record<string, { type: string; value: unknown }>;\n}\n\nexport interface NgsiV2QueryOptions {\n  type?: string;\n  q?: string;\n  limit?: number;\n  offset?: number;\n  attrs?: string;\n  options?: string;\n}\n\nexport class NgsiV2Client {\n  private baseUrl: string;\n  private headers: Record<string, string>;\n\n  constructor(config: NgsiV2ClientConfig) {\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '');\n    this.headers = {\n      'Content-Type': 'application/json',\n      Accept: 'application/json',\n    };\n    if (config.service) this.headers['Fiware-Service'] = config.service;\n    if (config.servicePath) this.headers['Fiware-ServicePath'] = config.servicePath;\n  }\n\n  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {\n    const res = await fetch(`${this.baseUrl}${path}`, {\n      method,\n      headers: this.headers,\n      body: body !== undefined ? JSON.stringify(body) : undefined,\n    });\n    if (!res.ok) {\n      const err = await res.json().catch(() => ({ error: `HTTP ${res.status}` })) as Record<string, unknown>;\n      const description = typeof err['description'] === 'string' ? err['description'] : undefined;\n      const error = typeof err['error'] === 'string' ? err['error'] : undefined;\n      throw new Error(description ?? error ?? `HTTP ${res.status}`);\n    }\n    if (res.status === 201 || res.status === 204) return undefined as T;\n    return res.json() as Promise<T>;\n  }\n\n  /** List entities */\n  async getEntities(options?: NgsiV2QueryOptions): Promise<NgsiV2Entity[]> {\n    const sp = new URLSearchParams();\n    if (options?.type) sp.set('type', options.type);\n    if (options?.q) sp.set('q', options.q);\n    if (options?.limit !== undefined) sp.set('limit', String(options.limit));\n    if (options?.offset !== undefined) sp.set('offset', String(options.offset));\n    if (options?.attrs) sp.set('attrs', options.attrs);\n    if (options?.options) sp.set('options', options.options);\n    const qs = sp.toString();\n    return this.request<NgsiV2Entity[]>('GET', `/v2/entities${qs ? '?' + qs : ''}`);\n  }\n\n  /** Get single entity by ID */\n  async getEntity(entityId: string, options?: { attrs?: string; options?: string }): Promise<NgsiV2Entity> {\n    const sp = new URLSearchParams();\n    if (options?.attrs) sp.set('attrs', options.attrs);\n    if (options?.options) sp.set('options', options.options);\n    const qs = sp.toString();\n    return this.request<NgsiV2Entity>('GET', `/v2/entities/${encodeURIComponent(entityId)}${qs ? '?' + qs : ''}`);\n  }\n\n  /** Create entity */\n  async createEntity(entity: NgsiV2Entity): Promise<void> {\n    await this.request<void>('POST', '/v2/entities', entity);\n  }\n\n  /** Update entity attributes (partial) */\n  async updateEntityAttributes(entityId: string, attrs: Record<string, NgsiV2Attribute>): Promise<void> {\n    await this.request<void>('PATCH', `/v2/entities/${encodeURIComponent(entityId)}/attrs`, attrs);\n  }\n\n  /** Delete entity */\n  async deleteEntity(entityId: string): Promise<void> {\n    await this.request<void>('DELETE', `/v2/entities/${encodeURIComponent(entityId)}`);\n  }\n}\n\nexport function createNgsiV2Client(config: NgsiV2ClientConfig): NgsiV2Client {\n  return new NgsiV2Client(config);\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAwCO,IAAM,eAAN,MAAmB;AAAA,EAIxB,YAAY,QAA4B;AAHxC,wBAAQ;AACR,wBAAQ;AAGN,SAAK,UAAU,OAAO,QAAQ,QAAQ,OAAO,EAAE;AAC/C,SAAK,UAAU;AAAA,MACb,gBAAgB;AAAA,MAChB,QAAQ;AAAA,IACV;AACA,QAAI,OAAO,QAAS,MAAK,QAAQ,gBAAgB,IAAI,OAAO;AAC5D,QAAI,OAAO,YAAa,MAAK,QAAQ,oBAAoB,IAAI,OAAO;AAAA,EACtE;AAAA,EAEA,MAAc,QAAW,QAAgB,MAAc,MAA4B;AACjF,UAAM,MAAM,MAAM,MAAM,GAAG,KAAK,OAAO,GAAG,IAAI,IAAI;AAAA,MAChD;AAAA,MACA,SAAS,KAAK;AAAA,MACd,MAAM,SAAS,SAAY,KAAK,UAAU,IAAI,IAAI;AAAA,IACpD,CAAC;AACD,QAAI,CAAC,IAAI,IAAI;AACX,YAAM,MAAM,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,EAAE,OAAO,QAAQ,IAAI,MAAM,GAAG,EAAE;AAC1E,YAAM,cAAc,OAAO,IAAI,aAAa,MAAM,WAAW,IAAI,aAAa,IAAI;AAClF,YAAM,QAAQ,OAAO,IAAI,OAAO,MAAM,WAAW,IAAI,OAAO,IAAI;AAChE,YAAM,IAAI,MAAM,eAAe,SAAS,QAAQ,IAAI,MAAM,EAAE;AAAA,IAC9D;AACA,QAAI,IAAI,WAAW,OAAO,IAAI,WAAW,IAAK,QAAO;AACrD,WAAO,IAAI,KAAK;AAAA,EAClB;AAAA;AAAA,EAGA,MAAM,YAAY,SAAuD;AACvE,UAAM,KAAK,IAAI,gBAAgB;AAC/B,QAAI,SAAS,KAAM,IAAG,IAAI,QAAQ,QAAQ,IAAI;AAC9C,QAAI,SAAS,EAAG,IAAG,IAAI,KAAK,QAAQ,CAAC;AACrC,QAAI,SAAS,UAAU,OAAW,IAAG,IAAI,SAAS,OAAO,QAAQ,KAAK,CAAC;AACvE,QAAI,SAAS,WAAW,OAAW,IAAG,IAAI,UAAU,OAAO,QAAQ,MAAM,CAAC;AAC1E,QAAI,SAAS,MAAO,IAAG,IAAI,SAAS,QAAQ,KAAK;AACjD,QAAI,SAAS,QAAS,IAAG,IAAI,WAAW,QAAQ,OAAO;AACvD,UAAM,KAAK,GAAG,SAAS;AACvB,WAAO,KAAK,QAAwB,OAAO,eAAe,KAAK,MAAM,KAAK,EAAE,EAAE;AAAA,EAChF;AAAA;AAAA,EAGA,MAAM,UAAU,UAAkB,SAAuE;AACvG,UAAM,KAAK,IAAI,gBAAgB;AAC/B,QAAI,SAAS,MAAO,IAAG,IAAI,SAAS,QAAQ,KAAK;AACjD,QAAI,SAAS,QAAS,IAAG,IAAI,WAAW,QAAQ,OAAO;AACvD,UAAM,KAAK,GAAG,SAAS;AACvB,WAAO,KAAK,QAAsB,OAAO,gBAAgB,mBAAmB,QAAQ,CAAC,GAAG,KAAK,MAAM,KAAK,EAAE,EAAE;AAAA,EAC9G;AAAA;AAAA,EAGA,MAAM,aAAa,QAAqC;AACtD,UAAM,KAAK,QAAc,QAAQ,gBAAgB,MAAM;AAAA,EACzD;AAAA;AAAA,EAGA,MAAM,uBAAuB,UAAkB,OAAuD;AACpG,UAAM,KAAK,QAAc,SAAS,gBAAgB,mBAAmB,QAAQ,CAAC,UAAU,KAAK;AAAA,EAC/F;AAAA;AAAA,EAGA,MAAM,aAAa,UAAiC;AAClD,UAAM,KAAK,QAAc,UAAU,gBAAgB,mBAAmB,QAAQ,CAAC,EAAE;AAAA,EACnF;AACF;AAEO,SAAS,mBAAmB,QAA0C;AAC3E,SAAO,IAAI,aAAa,MAAM;AAChC;",
+  "names": []
+}

package/ngsi-v2/index.d.ts

@@ -0,0 +1,58 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * NGSIv2 basic client — bundled per ADR論点2=a (殿裁可確定)
+ *
+ * Scope: basic entity CRUD only. No subscriptions, no batch ops.
+ * For NGSI-LD, use the core GeonicDB client instead.
+ */
+export interface NgsiV2ClientConfig {
+	baseUrl: string;
+	/** FIWARE service (tenant) */
+	service?: string;
+	/** FIWARE service path */
+	servicePath?: string;
+}
+export interface NgsiV2Entity {
+	id: string;
+	type: string;
+	[key: string]: string | NgsiV2Attribute | undefined;
+}
+export interface NgsiV2Attribute {
+	type: string;
+	value: string | number | boolean | object | null;
+	metadata?: Record<string, {
+		type: string;
+		value: unknown;
+	}>;
+}
+export interface NgsiV2QueryOptions {
+	type?: string;
+	q?: string;
+	limit?: number;
+	offset?: number;
+	attrs?: string;
+	options?: string;
+}
+export declare class NgsiV2Client {
+	private baseUrl;
+	private headers;
+	constructor(config: NgsiV2ClientConfig);
+	private request;
+	/** List entities */
+	getEntities(options?: NgsiV2QueryOptions): Promise<NgsiV2Entity[]>;
+	/** Get single entity by ID */
+	getEntity(entityId: string, options?: {
+		attrs?: string;
+		options?: string;
+	}): Promise<NgsiV2Entity>;
+	/** Create entity */
+	createEntity(entity: NgsiV2Entity): Promise<void>;
+	/** Update entity attributes (partial) */
+	updateEntityAttributes(entityId: string, attrs: Record<string, NgsiV2Attribute>): Promise<void>;
+	/** Delete entity */
+	deleteEntity(entityId: string): Promise<void>;
+}
+export declare function createNgsiV2Client(config: NgsiV2ClientConfig): NgsiV2Client;
+
+export {};

package/ngsi-v2/index.mjs

@@ -0,0 +1,73 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/sdk/ngsi-v2/index.ts
+var NgsiV2Client = class {
+  constructor(config) {
+    __publicField(this, "baseUrl");
+    __publicField(this, "headers");
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (config.service) this.headers["Fiware-Service"] = config.service;
+    if (config.servicePath) this.headers["Fiware-ServicePath"] = config.servicePath;
+  }
+  async request(method, path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: this.headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ error: `HTTP ${res.status}` }));
+      const description = typeof err["description"] === "string" ? err["description"] : void 0;
+      const error = typeof err["error"] === "string" ? err["error"] : void 0;
+      throw new Error(description ?? error ?? `HTTP ${res.status}`);
+    }
+    if (res.status === 201 || res.status === 204) return void 0;
+    return res.json();
+  }
+  /** List entities */
+  async getEntities(options) {
+    const sp = new URLSearchParams();
+    if (options?.type) sp.set("type", options.type);
+    if (options?.q) sp.set("q", options.q);
+    if (options?.limit !== void 0) sp.set("limit", String(options.limit));
+    if (options?.offset !== void 0) sp.set("offset", String(options.offset));
+    if (options?.attrs) sp.set("attrs", options.attrs);
+    if (options?.options) sp.set("options", options.options);
+    const qs = sp.toString();
+    return this.request("GET", `/v2/entities${qs ? "?" + qs : ""}`);
+  }
+  /** Get single entity by ID */
+  async getEntity(entityId, options) {
+    const sp = new URLSearchParams();
+    if (options?.attrs) sp.set("attrs", options.attrs);
+    if (options?.options) sp.set("options", options.options);
+    const qs = sp.toString();
+    return this.request("GET", `/v2/entities/${encodeURIComponent(entityId)}${qs ? "?" + qs : ""}`);
+  }
+  /** Create entity */
+  async createEntity(entity) {
+    await this.request("POST", "/v2/entities", entity);
+  }
+  /** Update entity attributes (partial) */
+  async updateEntityAttributes(entityId, attrs) {
+    await this.request("PATCH", `/v2/entities/${encodeURIComponent(entityId)}/attrs`, attrs);
+  }
+  /** Delete entity */
+  async deleteEntity(entityId) {
+    await this.request("DELETE", `/v2/entities/${encodeURIComponent(entityId)}`);
+  }
+};
+function createNgsiV2Client(config) {
+  return new NgsiV2Client(config);
+}
+export {
+  NgsiV2Client,
+  createNgsiV2Client
+};
+//# sourceMappingURL=index.mjs.map

package/ngsi-v2/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/sdk/ngsi-v2/index.ts"],
+  "sourcesContent": ["// SPDX-License-Identifier: MIT\n// Copyright (c) 2026 Geolonia Inc.\n// See LICENSE in src/sdk/ for full license text.\n\n/**\n * NGSIv2 basic client \u2014 bundled per ADR\u8AD6\u70B92=a (\u6BBF\u88C1\u53EF\u78BA\u5B9A)\n *\n * Scope: basic entity CRUD only. No subscriptions, no batch ops.\n * For NGSI-LD, use the core GeonicDB client instead.\n */\n\nexport interface NgsiV2ClientConfig {\n  baseUrl: string;\n  /** FIWARE service (tenant) */\n  service?: string;\n  /** FIWARE service path */\n  servicePath?: string;\n}\n\nexport interface NgsiV2Entity {\n  id: string;\n  type: string;\n  [key: string]: string | NgsiV2Attribute | undefined;\n}\n\nexport interface NgsiV2Attribute {\n  type: string;\n  value: string | number | boolean | object | null;\n  metadata?: Record<string, { type: string; value: unknown }>;\n}\n\nexport interface NgsiV2QueryOptions {\n  type?: string;\n  q?: string;\n  limit?: number;\n  offset?: number;\n  attrs?: string;\n  options?: string;\n}\n\nexport class NgsiV2Client {\n  private baseUrl: string;\n  private headers: Record<string, string>;\n\n  constructor(config: NgsiV2ClientConfig) {\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '');\n    this.headers = {\n      'Content-Type': 'application/json',\n      Accept: 'application/json',\n    };\n    if (config.service) this.headers['Fiware-Service'] = config.service;\n    if (config.servicePath) this.headers['Fiware-ServicePath'] = config.servicePath;\n  }\n\n  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {\n    const res = await fetch(`${this.baseUrl}${path}`, {\n      method,\n      headers: this.headers,\n      body: body !== undefined ? JSON.stringify(body) : undefined,\n    });\n    if (!res.ok) {\n      const err = await res.json().catch(() => ({ error: `HTTP ${res.status}` })) as Record<string, unknown>;\n      const description = typeof err['description'] === 'string' ? err['description'] : undefined;\n      const error = typeof err['error'] === 'string' ? err['error'] : undefined;\n      throw new Error(description ?? error ?? `HTTP ${res.status}`);\n    }\n    if (res.status === 201 || res.status === 204) return undefined as T;\n    return res.json() as Promise<T>;\n  }\n\n  /** List entities */\n  async getEntities(options?: NgsiV2QueryOptions): Promise<NgsiV2Entity[]> {\n    const sp = new URLSearchParams();\n    if (options?.type) sp.set('type', options.type);\n    if (options?.q) sp.set('q', options.q);\n    if (options?.limit !== undefined) sp.set('limit', String(options.limit));\n    if (options?.offset !== undefined) sp.set('offset', String(options.offset));\n    if (options?.attrs) sp.set('attrs', options.attrs);\n    if (options?.options) sp.set('options', options.options);\n    const qs = sp.toString();\n    return this.request<NgsiV2Entity[]>('GET', `/v2/entities${qs ? '?' + qs : ''}`);\n  }\n\n  /** Get single entity by ID */\n  async getEntity(entityId: string, options?: { attrs?: string; options?: string }): Promise<NgsiV2Entity> {\n    const sp = new URLSearchParams();\n    if (options?.attrs) sp.set('attrs', options.attrs);\n    if (options?.options) sp.set('options', options.options);\n    const qs = sp.toString();\n    return this.request<NgsiV2Entity>('GET', `/v2/entities/${encodeURIComponent(entityId)}${qs ? '?' + qs : ''}`);\n  }\n\n  /** Create entity */\n  async createEntity(entity: NgsiV2Entity): Promise<void> {\n    await this.request<void>('POST', '/v2/entities', entity);\n  }\n\n  /** Update entity attributes (partial) */\n  async updateEntityAttributes(entityId: string, attrs: Record<string, NgsiV2Attribute>): Promise<void> {\n    await this.request<void>('PATCH', `/v2/entities/${encodeURIComponent(entityId)}/attrs`, attrs);\n  }\n\n  /** Delete entity */\n  async deleteEntity(entityId: string): Promise<void> {\n    await this.request<void>('DELETE', `/v2/entities/${encodeURIComponent(entityId)}`);\n  }\n}\n\nexport function createNgsiV2Client(config: NgsiV2ClientConfig): NgsiV2Client {\n  return new NgsiV2Client(config);\n}\n"],
+  "mappings": ";;;;;AAwCO,IAAM,eAAN,MAAmB;AAAA,EAIxB,YAAY,QAA4B;AAHxC,wBAAQ;AACR,wBAAQ;AAGN,SAAK,UAAU,OAAO,QAAQ,QAAQ,OAAO,EAAE;AAC/C,SAAK,UAAU;AAAA,MACb,gBAAgB;AAAA,MAChB,QAAQ;AAAA,IACV;AACA,QAAI,OAAO,QAAS,MAAK,QAAQ,gBAAgB,IAAI,OAAO;AAC5D,QAAI,OAAO,YAAa,MAAK,QAAQ,oBAAoB,IAAI,OAAO;AAAA,EACtE;AAAA,EAEA,MAAc,QAAW,QAAgB,MAAc,MAA4B;AACjF,UAAM,MAAM,MAAM,MAAM,GAAG,KAAK,OAAO,GAAG,IAAI,IAAI;AAAA,MAChD;AAAA,MACA,SAAS,KAAK;AAAA,MACd,MAAM,SAAS,SAAY,KAAK,UAAU,IAAI,IAAI;AAAA,IACpD,CAAC;AACD,QAAI,CAAC,IAAI,IAAI;AACX,YAAM,MAAM,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,EAAE,OAAO,QAAQ,IAAI,MAAM,GAAG,EAAE;AAC1E,YAAM,cAAc,OAAO,IAAI,aAAa,MAAM,WAAW,IAAI,aAAa,IAAI;AAClF,YAAM,QAAQ,OAAO,IAAI,OAAO,MAAM,WAAW,IAAI,OAAO,IAAI;AAChE,YAAM,IAAI,MAAM,eAAe,SAAS,QAAQ,IAAI,MAAM,EAAE;AAAA,IAC9D;AACA,QAAI,IAAI,WAAW,OAAO,IAAI,WAAW,IAAK,QAAO;AACrD,WAAO,IAAI,KAAK;AAAA,EAClB;AAAA;AAAA,EAGA,MAAM,YAAY,SAAuD;AACvE,UAAM,KAAK,IAAI,gBAAgB;AAC/B,QAAI,SAAS,KAAM,IAAG,IAAI,QAAQ,QAAQ,IAAI;AAC9C,QAAI,SAAS,EAAG,IAAG,IAAI,KAAK,QAAQ,CAAC;AACrC,QAAI,SAAS,UAAU,OAAW,IAAG,IAAI,SAAS,OAAO,QAAQ,KAAK,CAAC;AACvE,QAAI,SAAS,WAAW,OAAW,IAAG,IAAI,UAAU,OAAO,QAAQ,MAAM,CAAC;AAC1E,QAAI,SAAS,MAAO,IAAG,IAAI,SAAS,QAAQ,KAAK;AACjD,QAAI,SAAS,QAAS,IAAG,IAAI,WAAW,QAAQ,OAAO;AACvD,UAAM,KAAK,GAAG,SAAS;AACvB,WAAO,KAAK,QAAwB,OAAO,eAAe,KAAK,MAAM,KAAK,EAAE,EAAE;AAAA,EAChF;AAAA;AAAA,EAGA,MAAM,UAAU,UAAkB,SAAuE;AACvG,UAAM,KAAK,IAAI,gBAAgB;AAC/B,QAAI,SAAS,MAAO,IAAG,IAAI,SAAS,QAAQ,KAAK;AACjD,QAAI,SAAS,QAAS,IAAG,IAAI,WAAW,QAAQ,OAAO;AACvD,UAAM,KAAK,GAAG,SAAS;AACvB,WAAO,KAAK,QAAsB,OAAO,gBAAgB,mBAAmB,QAAQ,CAAC,GAAG,KAAK,MAAM,KAAK,EAAE,EAAE;AAAA,EAC9G;AAAA;AAAA,EAGA,MAAM,aAAa,QAAqC;AACtD,UAAM,KAAK,QAAc,QAAQ,gBAAgB,MAAM;AAAA,EACzD;AAAA;AAAA,EAGA,MAAM,uBAAuB,UAAkB,OAAuD;AACpG,UAAM,KAAK,QAAc,SAAS,gBAAgB,mBAAmB,QAAQ,CAAC,UAAU,KAAK;AAAA,EAC/F;AAAA;AAAA,EAGA,MAAM,aAAa,UAAiC;AAClD,UAAM,KAAK,QAAc,UAAU,gBAAgB,mBAAmB,QAAQ,CAAC,EAAE;AAAA,EACnF;AACF;AAEO,SAAS,mBAAmB,QAA0C;AAC3E,SAAO,IAAI,aAAa,MAAM;AAChC;",
+  "names": []
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@geolonia/geonicdb-sdk",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "GeonicDB JavaScript SDK — NGSI-LD Context Broker client for browser and Node.js",
   "main": "geonicdb.cjs",
   "module": "geonicdb.mjs",
   "types": "geonicdb.d.ts",
   "browser": "geonicdb.iife.js",
+  "sideEffects": false,
   "exports": {
     ".": {
       "import": {
@@ -16,12 +17,46 @@
         "types": "./geonicdb.d.ts",
         "default": "./geonicdb.cjs"
       }
+    },
+    "./react": {
+      "import": {
+        "types": "./react/index.d.ts",
+        "default": "./react/index.mjs"
+      },
+      "require": {
+        "types": "./react/index.d.ts",
+        "default": "./react/index.cjs"
+      }
+    },
+    "./ngsi-v2": {
+      "import": {
+        "types": "./ngsi-v2/index.d.ts",
+        "default": "./ngsi-v2/index.mjs"
+      },
+      "require": {
+        "types": "./ngsi-v2/index.d.ts",
+        "default": "./ngsi-v2/index.cjs"
+      }
     }
   },
   "files": [
     "geonicdb.*",
+    "react/",
+    "ngsi-v2/",
     "LICENSE"
   ],
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "@geolonia/embed": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@geolonia/embed": {
+      "optional": true
+    }
+  },
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/react/index.cjs

@@ -0,0 +1,266 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sdk/react/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GeonicDbMap: () => GeonicDbMap,
+  useLdEntities: () => useLdEntities,
+  useTemporalData: () => useTemporalData
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/sdk/react/hooks.ts
+var import_react = require("react");
+function useLdEntities(client, options) {
+  const [entities, setEntities] = (0, import_react.useState)([]);
+  const [loading, setLoading] = (0, import_react.useState)(true);
+  const [error, setError] = (0, import_react.useState)(null);
+  const genRef = (0, import_react.useRef)(0);
+  const params = {};
+  if (options?.type) params.type = options.type;
+  if (options?.limit) params.limit = options.limit;
+  if (options?.attrs) params.attrs = options.attrs.join(",");
+  if (options?.q) params.q = options.q;
+  if (options?.scopeQ) params.scopeQ = options.scopeQ;
+  const paramsKey = JSON.stringify(params);
+  const fetchEntities = (0, import_react.useCallback)(async () => {
+    const gen = ++genRef.current;
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await client.getEntities(params);
+      if (genRef.current === gen) setEntities(data);
+    } catch (err) {
+      if (genRef.current === gen) setError(err instanceof Error ? err : new Error("Unknown error"));
+    } finally {
+      if (genRef.current === gen) setLoading(false);
+    }
+  }, [client, paramsKey]);
+  (0, import_react.useEffect)(() => {
+    void fetchEntities();
+    return () => {
+      genRef.current++;
+    };
+  }, [fetchEntities]);
+  return { entities, loading, error, refetch: fetchEntities };
+}
+function useTemporalData(client, options) {
+  const [data, setData] = (0, import_react.useState)([]);
+  const [loading, setLoading] = (0, import_react.useState)(false);
+  const [error, setError] = (0, import_react.useState)(null);
+  const genRef = (0, import_react.useRef)(0);
+  const enabled = options.enabled !== false;
+  const optionsKey = JSON.stringify(options);
+  const fetchData = (0, import_react.useCallback)(async () => {
+    const gen = ++genRef.current;
+    if (!enabled || !client) {
+      setData([]);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      if (options.id) {
+        const entity = await client.getTemporalEntity(options.id);
+        if (genRef.current === gen) setData([entity]);
+      } else {
+        const entities = await client.getTemporalEntities(options);
+        if (genRef.current === gen) setData(entities);
+      }
+    } catch (err) {
+      if (genRef.current === gen) setError(err instanceof Error ? err : new Error("Unknown error"));
+    } finally {
+      if (genRef.current === gen) setLoading(false);
+    }
+  }, [client, optionsKey]);
+  (0, import_react.useEffect)(() => {
+    void fetchData();
+    return () => {
+      genRef.current++;
+    };
+  }, [fetchData]);
+  return { data, loading, error, refetch: fetchData };
+}
+
+// src/sdk/react/GeonicDbMap.tsx
+var import_react2 = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var DEFAULT_STYLE = "geolonia/basic";
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function getEntityLocation(entity) {
+  const location = entity.location;
+  if (!location || typeof location === "string") return null;
+  const ldLoc = location;
+  if (ldLoc.type === "GeoProperty" && ldLoc.value?.type === "Point" && Array.isArray(ldLoc.value.coordinates)) {
+    return ldLoc.value.coordinates;
+  }
+  const v2Loc = location;
+  if (v2Loc.value?.type === "Point" && Array.isArray(v2Loc.value.coordinates)) {
+    return v2Loc.value.coordinates;
+  }
+  const kv = location;
+  if (kv.type === "Point" && Array.isArray(kv.coordinates)) {
+    return kv.coordinates;
+  }
+  return null;
+}
+function getMarkerColor(entityType) {
+  const colors = {
+    Room: "#3b82f6",
+    ParkingSpot: "#22c55e",
+    AirQualitySensor: "#f59e0b",
+    TrafficFlow: "#ef4444",
+    EnvironmentSensor: "#8b5cf6",
+    EnvSensor: "#8b5cf6",
+    TemperatureSensor: "#f97316",
+    GeoFeature: "#0ea5e9"
+  };
+  return colors[entityType] ?? "#6b7280";
+}
+function GeonicDbMap({
+  center = [139.7671, 35.6812],
+  zoom = 13,
+  styleUrl,
+  entities = [],
+  onEntityClick,
+  onMapClick,
+  className = "",
+  style: customStyle,
+  showPopups = true,
+  fitToMarkers = false
+}) {
+  const mapContainerRef = (0, import_react2.useRef)(null);
+  const mapRef = (0, import_react2.useRef)(null);
+  const markersRef = (0, import_react2.useRef)([]);
+  const mapLoadedRef = (0, import_react2.useRef)(false);
+  const pendingUpdateRef = (0, import_react2.useRef)(false);
+  (0, import_react2.useEffect)(() => {
+    if (!mapContainerRef.current) return;
+    mapLoadedRef.current = false;
+    void import("@geolonia/embed").then(({ Map: GeoMap }) => {
+      if (!mapContainerRef.current) return;
+      const map = new GeoMap({
+        container: mapContainerRef.current,
+        style: styleUrl ?? DEFAULT_STYLE,
+        center,
+        zoom
+      });
+      mapRef.current = map;
+      const onReady = () => {
+        mapLoadedRef.current = true;
+        if (pendingUpdateRef.current) {
+          pendingUpdateRef.current = false;
+          window.dispatchEvent(new CustomEvent("geonicdb-map-ready"));
+        }
+      };
+      map.on("load", onReady);
+      map.once("idle", onReady);
+      if (onMapClick) {
+        map.on("click", (e) => {
+          onMapClick([e.lngLat.lng, e.lngLat.lat]);
+        });
+      }
+    });
+    return () => {
+      if (mapRef.current) {
+        mapRef.current.remove();
+        mapRef.current = null;
+        mapLoadedRef.current = false;
+      }
+    };
+  }, [styleUrl]);
+  const doUpdate = (0, import_react2.useCallback)(() => {
+    const map = mapRef.current;
+    if (!map) return;
+    markersRef.current.forEach((marker) => marker.remove());
+    markersRef.current = [];
+    void import("@geolonia/embed").then(({ Marker, geolonia }) => {
+      entities.forEach((entity) => {
+        const coords = getEntityLocation(entity);
+        if (!coords) return;
+        const color = getMarkerColor(entity.type);
+        const el = document.createElement("div");
+        el.style.cssText = `width:24px;height:24px;background-color:${color};border:2px solid white;border-radius:50%;cursor:pointer;box-shadow:0 2px 4px rgba(0,0,0,0.3);`;
+        const marker = new Marker({ element: el }).setLngLat(coords).addTo(map);
+        if (showPopups && geolonia?.Popup) {
+          const popup = new geolonia.Popup({ closeButton: false, closeOnClick: false, offset: 15 }).setHTML(`<div style="font-family:sans-serif;font-size:12px;"><strong>${escapeHtml(entity.id)}</strong><br/><span style="color:#666">${escapeHtml(entity.type)}</span></div>`);
+          el.addEventListener("mouseenter", () => {
+            marker.setPopup(popup);
+            popup.addTo(map);
+          });
+          el.addEventListener("mouseleave", () => {
+            popup.remove();
+          });
+        }
+        if (onEntityClick) {
+          el.addEventListener("click", (e) => {
+            e.stopPropagation();
+            onEntityClick(entity);
+          });
+        }
+        markersRef.current.push(marker);
+      });
+      if (fitToMarkers && markersRef.current.length > 0) {
+        const allCoords = entities.map(getEntityLocation).filter((c) => c !== null);
+        if (allCoords.length === 1 && allCoords[0]) {
+          map.flyTo({ center: allCoords[0], zoom: 14 });
+        } else if (allCoords.length > 1) {
+          const bounds = allCoords.reduce(
+            (b, coord) => [[Math.min(b[0][0], coord[0]), Math.min(b[0][1], coord[1])], [Math.max(b[1][0], coord[0]), Math.max(b[1][1], coord[1])]],
+            [[allCoords[0][0], allCoords[0][1]], [allCoords[0][0], allCoords[0][1]]]
+          );
+          map.fitBounds(bounds, { padding: 30 });
+        }
+      }
+    });
+  }, [entities, onEntityClick, showPopups, fitToMarkers]);
+  (0, import_react2.useEffect)(() => {
+    if (mapLoadedRef.current) {
+      doUpdate();
+    } else {
+      pendingUpdateRef.current = true;
+      const handler = () => doUpdate();
+      window.addEventListener("geonicdb-map-ready", handler, { once: true });
+      return () => window.removeEventListener("geonicdb-map-ready", handler);
+    }
+  }, [doUpdate]);
+  const defaultStyle = { width: "100%", height: "100%", minHeight: "400px" };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      ref: mapContainerRef,
+      className,
+      style: { ...defaultStyle, ...customStyle }
+    }
+  );
+}
+//# sourceMappingURL=index.cjs.map