@geolonia/geonicdb-sdk 0.10.0 → 0.11.0

package/geonicdb.d.ts

@@ -1,30 +1,503 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * Copyright (c) 2026 Geolonia Inc.
+ * Released under the MIT License. See src/sdk/LICENSE for details.
+ */
+/** Options for the GeonicDB SDK constructor. */
+export interface GeonicDBOptions {
+	/** API key (or use data-api-key attribute on script tag) */
+	apiKey?: string;
+	/** Tenant name (or use data-tenant attribute on script tag) */
+	tenant?: string;
+	/** API base URL (auto-detected from script src if omitted) */
+	baseUrl?: string;
+	/** WebSocket endpoint URL (auto-detected from baseUrl if omitted) */
+	wsEndpoint?: string;
+	/** Enable debug logging to console (default: false) */
+	debug?: boolean;
+	/**
+	 * Enable in-memory client-side cache with automatic ETag/If-None-Match
+	 * handling and request deduplication. (Phase A, default: true)
+	 */
+	cache?: boolean;
+	/**
+	 * Maximum number of cached entries (LRU eviction beyond this size).
+	 * Only meaningful when `cache` is enabled. Default: 1000.
+	 */
+	cacheMaxEntries?: number;
+	/**
+	 * #1105: Anonymous mode. When true, the SDK skips token acquisition and
+	 * sends requests without an `Authorization` header. The server treats
+	 * such requests as `role: 'anonymous'` and lets the XACML policy engine
+	 * decide whether to permit them.
+	 *
+	 * - Cannot be combined with `apiKey` (constructor throws).
+	 * - `login()` / `setCredentials()` switches the SDK out of anonymous mode
+	 *   for subsequent requests.
+	 * - `logout()` reverts to anonymous mode.
+	 * - WebSocket `connect()` is not supported in anonymous mode and throws.
+	 */
+	anonymous?: boolean;
+}
+/** Options for the SDK polling helper. */
+export interface PollOptions<T = unknown> {
+	/** Polling interval in milliseconds (default: 5000). */
+	interval?: number;
+	/** Called when fresh data is received from the server (200). */
+	onData?: (data: T) => void;
+	/** Called when the server responded 304 (no change since last poll). */
+	onNoChange?: () => void;
+	/** Called on transport / HTTP errors. Polling continues unless the handler stops it. */
+	onError?: (error: unknown) => void;
+}
+/** Handle returned by `db.poll(...)` to control the polling loop. */
+export interface PollHandle {
+	/** Stop the polling loop. Idempotent. */
+	stop(): void;
+}
+/** Options for setting credentials externally. */
+export interface CredentialsOptions {
+	/** Access token (JWT) */
+	token: string;
+	/** Token type — default: 'Bearer' */
+	tokenType?: "Bearer" | "DPoP";
+	/** Token lifetime in seconds (default: 3600) */
+	expiresIn?: number;
+	/** Refresh token for auto-renewal */
+	refreshToken?: string;
+}
+/** Credentials returned after a token refresh. */
+export interface RefreshedCredentials {
+	/** New access token */
+	token: string;
+	/** Token type */
+	tokenType: string;
+	/** Token lifetime in seconds */
+	expiresIn: number;
+	/** New refresh token */
+	refreshToken: string;
+}
+/**
+ * Parameters for querying entities.
+ *
+ * NGSI-LD 1.6 §5.7.2 Query Entities が定める主要パラメータを網羅する (#1132)。
+ * 以前はサーバ側が georel / scopeQ / attrs / pick / omit / lang などを実装
+ * しているのに SDK 側で型と URL builder が `type / limit / offset / q` の
+ * 4 つしか持たず、`db.request()` に逃げる必要があった。
+ */
+export interface GetEntitiesParams {
+	/** Entity type filter */
+	type?: string;
+	/** Max results */
+	limit?: number;
+	/** Pagination offset */
+	offset?: number;
+	/** NGSI-LD query expression */
+	q?: string;
+	/** NGSI-LD scope query expression (`/foo`, `/foo/#`, `/foo/+`, `;` で OR) */
+	scopeQ?: string;
+	/** Geo-relation: `near`, `within`, `contains`, `intersects`, `disjoint`, `equals` */
+	georel?: string;
+	/** Geometry type: `Point`, `Polygon`, `LineString`, ... */
+	geometry?: string;
+	/** Coordinates string (semicolon-delimited pairs or flat comma-separated) */
+	coordinates?: string;
+	/** Comma-separated attribute names to retrieve */
+	attrs?: string;
+	/** Comma-separated attribute names to keep (alternative to attrs) */
+	pick?: string;
+	/** Comma-separated attribute names to remove */
+	omit?: string;
+	/** Language tag for LanguageProperty filtering */
+	lang?: string;
+	/** Order by field */
+	orderBy?: string;
+	/** Order direction: `asc` (default) or `desc` */
+	orderDirection?: "asc" | "desc";
+	/** Sort points by distance from a `near` query */
+	orderByDistance?: boolean;
+	/** Whether the response should include a count (server returns `NGSILD-Results-Count` header) */
+	count?: boolean;
+	/** GeoProperty key to use (default `location`) */
+	geoproperty?: string;
+}
+/** Parameters for counting entities. */
+export interface CountEntitiesParams {
+	/** Entity type filter */
+	type?: string;
+	/** NGSI-LD query expression */
+	q?: string;
+	/** NGSI-LD scope query expression (#1132) */
+	scopeQ?: string;
+}
+/** Options for subscribing to entity events via WebSocket. */
+export interface SubscribeOptions {
+	/** Entity types to subscribe to */
+	entityTypes?: string[];
+	/** Entity ID regex pattern */
+	idPattern?: string;
+	/** NGSI-LD scope query expression (#1132). Server-side filter; only events whose entity scope matches are delivered. */
+	scopeQ?: string;
+}
+/** Entity event received via WebSocket. */
+export interface EntityEvent {
+	/** Event type */
+	type: "entityCreated" | "entityUpdated" | "entityDeleted";
+	/** Tenant name */
+	tenant: string;
+	/** Service path */
+	servicePath: string;
+	/** Entity ID */
+	entityId: string;
+	/** Entity type */
+	entityType: string;
+	/** Entity attributes */
+	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[];
+	/** ISO 8601 timestamp */
+	timestamp: string;
+}
+/** Event fired when a reconnection attempt is starting. */
+export interface ReconnectingEvent {
+	/** Current reconnection attempt number */
+	attempt: number;
+	/** Delay in ms before this attempt */
+	delay: number;
+}
+/** Options for `db.login(...)`. */
+export interface LoginOptions {
+	/**
+	 * If true, keep the user signed in across page reloads by persisting the
+	 * session to IndexedDB. After a reload, call `db.restoreSession()` to
+	 * rehydrate the session; `db.logout()` clears the persisted entry.
+	 *
+	 * The session is bound to a non-extractable key (DPoP, RFC 9449) stored via
+	 * the structured clone algorithm — `extractable: false` is preserved, so the
+	 * key cannot be read back as JWK / PEM even with full DOM access. A token
+	 * leaked from localStorage stays unusable without this origin's IndexedDB.
+	 *
+	 * Default: false. Opt-out by design: shared-device flows should not enable
+	 * this. Has no effect when the runtime lacks Web Crypto — the session cannot
+	 * be sender-constrained, so it is not persisted.
+	 */
+	rememberSession?: boolean;
+}
+/** Response from the login endpoint. */
+export interface LoginResponse {
+	accessToken: string;
+	refreshToken: string;
+	expiresIn: number;
+	/**
+	 * Token scheme: `Bearer` (default) or `DPoP` when the session has been
+	 * sender-constrained via `/auth/dpop-bind` (RFC 9449). Optional for
+	 * backward compatibility with older server responses.
+	 */
+	tokenType?: "Bearer" | "DPoP";
+}
+/** Cache event payloads. */
+export interface CacheEvent {
+	/** Cache key (typically `${method}:${path}` form). */
+	key: string;
+	/** Resource path (without method prefix). */
+	path: string;
+}
+/** Map of event names to their payload types. */
+export interface GeonicDBEventMap {
+	entityCreated: EntityEvent;
+	entityUpdated: EntityEvent;
+	entityDeleted: EntityEvent;
+	open: undefined;
+	connected: undefined;
+	close: {
+		code: number;
+		reason: string;
+	};
+	disconnected: undefined;
+	reconnecting: ReconnectingEvent;
+	error: Error;
+	message: Record<string, unknown>;
+	tokenRefresh: RefreshedCredentials;
+	/** Fired when a request is served from the in-memory cache (304 received). */
+	cacheHit: CacheEvent;
+	/** Fired when a request misses cache and is fetched from the origin. */
+	cacheMiss: CacheEvent;
+	/** Fired when a cache entry is invalidated (e.g. by a WebSocket entity event). */
+	cacheInvalidated: CacheEvent;
+}
+/** Parameters for querying temporal entities. */
+export interface GetTemporalEntitiesParams {
+	/** Entity type filter */
+	type?: string;
+	/** Entity ID */
+	id?: string;
+	/** Entity ID pattern (regex) */
+	idPattern?: string;
+	/** Attribute names to retrieve */
+	attrs?: string;
+	/** NGSI-LD query expression */
+	q?: string;
+	/** Time property to use (observedAt, createdAt, modifiedAt) */
+	timeproperty?: string;
+	/** Start time (ISO 8601) */
+	timeAt?: string;
+	/** End time (ISO 8601) */
+	endTimeAt?: string;
+	/** Temporal relation (before, after, between) */
+	timerel?: string;
+	/** NGSI-LD scope query expression (#1132) */
+	scopeQ?: string;
+	/** Max results */
+	limit?: number;
+	/** Pagination offset */
+	offset?: number;
+}
+export type Listener<T> = (data: T) => void;
+declare class EventEmitter {
+	private _listeners;
+	on<K extends keyof GeonicDBEventMap>(event: K, callback: Listener<GeonicDBEventMap[K]>): this;
+	on(event: string, callback: Listener<unknown>): this;
+	off<K extends keyof GeonicDBEventMap>(event: K, callback?: Listener<GeonicDBEventMap[K]>): this;
+	off(event: string, callback?: Listener<unknown>): this;
+	protected emit<K extends keyof GeonicDBEventMap>(event: K, data?: GeonicDBEventMap[K]): void;
+	protected emit(event: string, data?: unknown): void;
+}
+/**
+ * Copyright (c) 2026 Geolonia Inc.
+ * Released under the MIT License. See src/sdk/LICENSE for details.
+ */
+/**
+ * Base error class for GeonicDB SDK.
+ * All SDK errors extend this class, allowing `instanceof GeonicDBError` checks.
+ */
+export declare class GeonicDBError extends Error {
+	/** HTTP status code (if applicable) */
+	readonly statusCode: number;
+	constructor(message: string, statusCode?: number);
+}
+/** 401 — Authentication failed (invalid credentials, expired token). */
+export declare class AuthenticationError extends GeonicDBError {
+	constructor(message?: string);
+}
+/** 403 — Authorization denied (insufficient permissions). */
+export declare class AuthorizationError extends GeonicDBError {
+	constructor(message?: string);
+}
+/** 404 — Resource not found. */
+export declare class NotFoundError extends GeonicDBError {
+	constructor(message?: string);
+}
+/** 409 — Conflict (e.g. entity already exists). */
+export declare class ConflictError extends GeonicDBError {
+	constructor(message?: string);
+}
+/** 422 — Validation error (bad request payload). */
+export declare class ValidationError extends GeonicDBError {
+	constructor(message?: string);
+}
+/** 429 — Rate limited. */
+export declare class RateLimitError extends GeonicDBError {
+	/** Seconds to wait before retrying (from Retry-After header) */
+	readonly retryAfter: number;
+	constructor(message?: string, retryAfter?: number);
+}
+/** Network error (fetch failed, DNS resolution, timeout). */
+export declare class NetworkError extends GeonicDBError {
+	constructor(message?: string);
+}
+/**
+ * GeonicDB SDK client.
+ *
+ * Handles API key auth (DPoP + PoW), Bearer JWT, entity CRUD,
+ * WebSocket event streaming, and automatic reconnection.
+ *
+ * @example
+ * ```typescript
+ * import GeonicDB from '@geolonia/geonicdb-sdk';
+ *
+ * const db = new GeonicDB({
+ *   apiKey: 'your-api-key',
+ *   tenant: 'your-tenant',
+ *   baseUrl: 'https://your-geonicdb.example.com',
+ * });
+ *
+ * const entities = await db.getEntities({ type: 'Room' });
+ * ```
+ */
+export declare class GeonicDB extends EventEmitter {
+	private _auth;
+	private _ws;
+	/**
+	 * Legacy callback for token refresh events.
+	 * Prefer `db.on('tokenRefresh', callback)` for new code.
+	 * @deprecated Use `db.on('tokenRefresh', callback)` instead.
+	 */
+	onTokenRefresh: ((creds: RefreshedCredentials) => void) | null;
+	constructor(options?: GeonicDBOptions);
+	/**
+	 * Drop every cached response. Useful in tests and on manual auth changes.
+	 *
+	 * Emits a `cacheInvalidated` event for each removed entry so listeners can
+	 * track explicit flushes (the WebSocket-driven auto-invalidation was removed
+	 * in #1060 to preserve the ETag/304 revalidation path; `clearCache()` is now
+	 * the only path that emits this event).
+	 */
+	clearCache(): void;
+	/**
+	 * Login with email and password.
+	 *
+	 * The session is sender-constrained with DPoP (RFC 9449) automatically and
+	 * transparently — there is no DPoP option to set. A token leaked from
+	 * storage (e.g. localStorage XSS) is therefore unusable from another origin.
+	 * On runtimes without Web Crypto, the SDK silently keeps a plain Bearer
+	 * session and login still succeeds.
+	 *
+	 * @example
+	 * ```ts
+	 * // Standard login — DPoP applied transparently when supported.
+	 * await db.login('user@example.com', 'password');
+	 *
+	 * // Keep the user signed in across page reloads (browser SPA UX).
+	 * await db.login('user@example.com', 'password', { rememberSession: true });
+	 * ```
+	 */
+	login(email: string, password: string, options?: LoginOptions): Promise<LoginResponse>;
+	/**
+	 * Rehydrate a session previously persisted via
+	 * `login(email, password, { rememberSession: true })`.
+	 *
+	 * Returns true if a session for this tenant was found and loaded; false
+	 * if there was no entry, IndexedDB is unavailable, or the persisted
+	 * session was malformed. Call this at app startup before deciding
+	 * whether to render the login form.
+	 *
+	 * @example
+	 * ```ts
+	 * const db = new GeonicDB({ baseUrl, tenant });
+	 * if (await db.restoreSession()) {
+	 *   // Session (tokens + non-extractable key) recovered — boot the app.
+	 * } else {
+	 *   // No session; show the login form.
+	 * }
+	 * ```
+	 */
+	restoreSession(): Promise<boolean>;
+	/**
+	 * Whether the SDK is currently operating in anonymous mode (no token held).
+	 * Returns true only when `anonymous: true` was passed to the constructor
+	 * AND no credentials have been set via `login()` / `setCredentials()`.
+	 */
+	isAnonymous(): boolean;
+	/**
+	 * Set credentials externally (e.g. from a login API response).
+	 * When tokenType is 'Bearer' with a refreshToken, DPoP/PoW is bypassed entirely.
+	 */
+	setCredentials(opts: CredentialsOptions): this;
+	/** Clear all credentials and disconnect. */
+	logout(): void;
+	/** Create a new entity. */
+	createEntity(entity: Record<string, unknown>): Promise<{
+		created: true;
+	}>;
+	/** Get a single entity by ID. */
+	getEntity(entityId: string): Promise<Record<string, unknown>>;
+	/** Query entities with optional filters. */
+	getEntities(params?: GetEntitiesParams): Promise<Record<string, unknown>[]>;
+	/**
+	 * Poll for entity list changes using ETag-based revalidation (#991 Phase A).
+	 *
+	 * The handle's `stop()` ends the loop. Each tick performs a normal
+	 * `getEntities()` call; the SDK's cache layer issues `If-None-Match`
+	 * automatically. The poll detects "no change" by comparing the previous
+	 * ETag with the response's ETag (the cache exposes the cached ETag on 304
+	 * replays as well, so the comparison stays valid in both 200 and 304
+	 * paths).
+	 *
+	 * @example
+	 * ```typescript
+	 * const handle = db.poll({ type: 'Room' }, {
+	 *   interval: 5000,
+	 *   onData: (rooms) => render(rooms),
+	 *   onNoChange: () => {},
+	 * });
+	 * // ...later
+	 * handle.stop();
+	 * ```
+	 */
+	poll(params: GetEntitiesParams | undefined, options: PollOptions<Record<string, unknown>[]>): PollHandle;
+	/** Count entities matching the given filters. */
+	count(params?: CountEntitiesParams): Promise<number>;
+	/** Update entity attributes (partial). */
+	updateEntity(entityId: string, attrs: Record<string, unknown>): Promise<{
+		updated: true;
+	}>;
+	/** Delete an entity. */
+	deleteEntity(entityId: string): Promise<{
+		deleted: true;
+	}>;
+	/** List all entity types. */
+	getTypes(): Promise<Record<string, unknown>[]>;
+	/** Get details for a specific entity type. */
+	getType(typeName: string): Promise<Record<string, unknown>>;
+	/** List all attributes. */
+	getAttributes(): Promise<Record<string, unknown>[]>;
+	/** Get details for a specific attribute. */
+	getAttribute(attrName: string): Promise<Record<string, unknown>>;
+	/** Query temporal entities. */
+	getTemporalEntities(params?: GetTemporalEntitiesParams): Promise<Record<string, unknown>[]>;
+	/** Get temporal representation of a single entity. */
+	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>>;
+	/** Update multiple entities in a single request. */
+	batchUpdate(entities: Record<string, unknown>[]): Promise<Record<string, unknown>>;
+	/** Delete multiple entities by ID. */
+	batchDelete(entityIds: string[]): Promise<Record<string, unknown>>;
+	/** GET request that returns parsed JSON or throws. */
+	private _jsonGet;
+	/** POST request that returns parsed JSON or throws. */
+	private _jsonPost;
+	/**
+	 * Make an authenticated API request.
+	 * Automatically checks response status, parses JSON, and throws on error.
+	 *
+	 * Empty bodies (`Content-Length: 0` 含む) は Content-Type に関係なく `null`
+	 * を返す (#1145)。NGSI-LD の POST / DELETE / PATCH 系は仕様上ボディが
+	 * 空だが、サーバ実装が `Content-Type: application/ld+json` を付けて返す
+	 * ケースがあり、そこで `res.json()` が SyntaxError を投げて止まっていた。
+	 */
+	request(method: string, path: string, body?: unknown): Promise<unknown>;
+	/**
+	 * Make an authenticated API request and return the raw Response object.
+	 * Use this when you need access to response headers (e.g. NGSILD-Results-Count).
+	 */
+	requestRaw(method: string, path: string, body?: unknown): Promise<Response>;
+	/** Establish WebSocket connection (authentication is automatic). */
+	connect(): Promise<void>;
+	/** Force-reconnect (closes existing connection, preserves subscriptions). */
+	reconnect(): Promise<void>;
+	/** Disconnect WebSocket (does not fire 'disconnected' event). */
+	disconnect(): void;
+	/** Check if WebSocket is currently open. */
+	isConnected(): boolean;
+	/** Subscribe to entity events (can be called before or after connect). */
+	subscribe(options?: SubscribeOptions): void;
+}
+/**
+ * 汎用クエリ文字列ビルダ。`undefined` / `null` は省略、`boolean` は
+ * `'true'` / `'false'` の文字列、`number` は `String(n)`、それ以外は文字列化。
+ * 配列 / オブジェクトはサポート対象外 (NGSI-LD 仕様内の全パラメータは
+ * primitive で表現できるため不要)。
+ */
+export declare function buildPathWithParams(path: string, params?: Record<string, unknown>): string;
+
 export {
-  AuthenticationError,
-  AuthorizationError,
-  ConflictError,
-  GeonicDB,
-  GeonicDBError,
-  NetworkError,
-  NotFoundError,
-  RateLimitError,
-  ValidationError,
-  buildPathWithParams,
-} from './index';
-export type {
-  CacheEvent,
-  CountEntitiesParams,
-  CredentialsOptions,
-  EntityEvent,
-  GeonicDBEventMap,
-  GeonicDBOptions,
-  GetEntitiesParams,
-  GetTemporalEntitiesParams,
-  LoginOptions,
-  LoginResponse,
-  PollHandle,
-  PollOptions,
-  ReconnectingEvent,
-  RefreshedCredentials,
-  SubscribeOptions,
-} from './index';
-export { default } from './index';
+	GeonicDB as default,
+};
+
+export {};