@aapicoits/powermap-web-sdk 1.0.1 → 1.1.1

package/dist/index.d.ts

@@ -1,226 +1,420 @@
-// ============================================================
-// PowerMap Web SDK — TypeScript Declaration File
-// Auto-generated from src/index.js JSDoc
-// ============================================================
-
-export interface PowerMapAuthOptions {
-  clientId: string;
-  clientSecret: string;
-}
-
-export interface PowerMapOptions {
-  /** The HTML element ID or element reference to mount the map into */
-  container: string | HTMLElement;
-  /** Initial map center as [longitude, latitude] */
-  center?: [number, number];
-  /** Initial zoom level */
-  zoom?: number;
-  /** Minimum zoom level */
-  minZoom?: number;
-  /** Maximum zoom level */
-  maxZoom?: number;
-  /** Map style name: 'th' | 'en' | 'dark' | 'gray' or a custom style URL */
-  style?: 'th' | 'en' | 'dark' | 'gray' | string;
-  /** API Key for map tiles */
-  mapApiKey: string;
-  /** Authentication credentials for services */
-  auth: PowerMapAuthOptions;
-  /** Disable all map interactions (zoom, pan, rotate) — preview mode */
-  previewOnly?: boolean;
-}
-
-export interface MarkerOptions {
-  /** [longitude, latitude] */
-  position: [number, number];
-  /** Marker type */
-  type?: 'start' | 'destination' | 'waypoint' | string;
-  /** Custom image URL */
-  iconUrl?: string;
-  /** Custom hex color for pinpoint marker (e.g. '#ff4444') */
-  color?: string;
-  /** FontAwesome icon class (e.g. 'fas fa-car') */
-  icon?: string;
-  /** Enable marker dragging */
-  draggable?: boolean;
-  /** HTML content or structured popup object */
-  popupContent?: string | { title?: string; body?: string; tag?: string; footer?: string };
-  /** Unique identifier for the marker */
-  id?: string;
-}
-
-export interface MarkerInstance {
-  id: string;
-  position: [number, number];
-  remove(): void;
-  setLngLat(lngLat: [number, number]): this;
-  getLngLat(): { lng: number; lat: number };
-  [key: string]: unknown;
-}
-
-export interface RouteOptions {
-  start: [number, number];
-  destination: [number, number];
-  waypoints?: [number, number][];
-  optimize?: boolean;
-  [key: string]: unknown;
-}
-
-export interface RouteStep {
-  distance: number;
-  distanceStr: string;
-  duration: number;
-  durationStr: string;
-  instruction?: string;
-  [key: string]: unknown;
-}
-
-export interface RouteDetails {
-  distance: number;
-  distanceStr: string;
-  duration: number;
-  durationStr: string;
-  steps: RouteStep[];
-}
-
-export interface RouteSummary {
-  distanceStr: string;
-  durationStr: string;
-}
-
-export interface SearchResult {
-  id: string;
-  name: string;
-  address?: string;
-  position: [number, number];
-  [key: string]: unknown;
-}
-
-export interface SearchOptions {
-  location?: [number, number];
-  lang?: string;
-  [key: string]: unknown;
-}
-
-export interface FlyToOptions {
-  center?: [number, number];
-  zoom?: number;
-  pitch?: number;
-  bearing?: number;
-  speed?: number;
-  curve?: number;
-  [key: string]: unknown;
-}
-
-export interface FitBoundsOptions {
-  padding?: number | { top: number; bottom: number; left: number; right: number };
-  maxZoom?: number;
-  [key: string]: unknown;
-}
-
-export type PowerMapEventName =
-  | 'mapLoaded'
-  | 'mapClick'
-  | 'mapLongClick'
-  | 'markerClick'
-  | 'markerDrag'
-  | 'markerDragEnd'
-  | 'poiClick'
-  | 'routeCalculated'
-  | 'modeChanged'
-  | 'error'
-  | string;
-
-export type PowerMapMode = 'standard' | 'indoor';
-
-export interface SetModeOptions {
-  buildingId?: string;
-  floorId?: string;
-  center?: [number, number];
-  [key: string]: unknown;
-}
-
-/**
- * PowerMap SDK Main Class
- *
- * Provides a high-level API for map rendering, markers, routing,
- * indoor navigation, and vehicle simulation.
- *
- * @example
- * const map = new PowerMap({
- *   container: 'map',
- *   mapApiKey: 'YOUR_KEY',
- *   auth: { clientId: '...', clientSecret: '...' }
- * })
- * .on('mapLoaded', () => console.log('Ready!'))
- * .setStyle('dark');
- */
-export declare class PowerMap {
-  constructor(options: PowerMapOptions);
-
-  // --- Events ---
-  on(event: PowerMapEventName, callback: (...args: unknown[]) => void): this;
-  off(event: PowerMapEventName, callback: (...args: unknown[]) => void): this;
-  onMapLoaded(callback: (data: { map: PowerMap }) => void): this;
-  onClick(callback: (event: unknown) => void): this;
-  onMapLongClick(callback: (event: unknown) => void): this;
-  onMarkerClick(callback: (data: { marker: MarkerInstance; originalEvent: unknown; options: unknown }) => void): this;
-  onPoiClick(callback: (data: { feature: unknown; lngLat: unknown; point: unknown }) => void): this;
-  onMarkerDrag(callback: (data: { marker: MarkerInstance; lngLat: [number, number] }) => void): this;
-  onMarkerDragEnd(callback: (data: { marker: MarkerInstance; lngLat: [number, number] }) => void): this;
-  onRouteCalculated(callback: (route: unknown) => void): this;
-  onError(callback: (error: Error) => void): this;
-
-  // --- Map Style & Mode ---
-  setStyle(name: 'th' | 'en' | 'dark' | 'gray' | string): this;
-  setMode(mode: PowerMapMode, options?: SetModeOptions): this;
-
-  // --- Controls ---
-  setNavigationControl(options: boolean | object): this;
-  setFullscreenControl(options: boolean | object): this;
-
-  // --- Camera ---
-  flyTo(options: FlyToOptions): this;
-  easeTo(options: FlyToOptions): this;
-  fitBounds(bounds: [[number, number], [number, number]], options?: FitBoundsOptions): this;
-  jumpTo(options: FlyToOptions): this;
-  setPitch(pitch: number, animate?: boolean): this;
-  setBearing(bearing: number, animate?: boolean): this;
-  zoomIn(): this;
-  zoomOut(): this;
-  rotateLeft(): this;
-  rotateRight(): this;
-  getCenter(): { lng: number; lat: number };
-  getZoom(): number;
-  getPitch(): number;
-  getBearing(): number;
-
-  // --- Markers ---
-  addMarker(options: MarkerOptions): MarkerInstance;
-  getMarker(id: string): MarkerInstance | null;
-  removeMarker(markerOrId: MarkerInstance | string): this;
-  updatePopup(marker: MarkerInstance, content: string | object): this;
-  clearMarkers(): this;
-
-  // --- Routing ---
-  addRoute(options: RouteOptions): Promise<unknown>;
-  clearRoutes(): this;
-  getRouteDetails(): RouteDetails | null;
-  getRouteSummary(): RouteSummary | null;
-  formatDistance(meters: number): string;
-  formatDuration(seconds: number): string;
-
-  // --- Search ---
-  search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
-
-  // --- Layers ---
-  showLayer(layerId: string): Promise<this>;
-  hideLayer(layerId: string): this;
-  toggleLayer(layerId: string): Promise<this>;
-
-  // --- Managers (advanced access) ---
-  readonly layers: unknown;
-  readonly geometry: unknown;
-  readonly indoor: unknown;
-  readonly editor: unknown;
-  debug(): unknown;
-}
+// ============================================================
+// PowerMap Web SDK — TypeScript Declaration File
+// Auto-generated from src/index.js JSDoc
+// ============================================================
+
+export interface PowerMapAuthOptions {
+  clientId: string;
+  clientSecret: string;
+}
+
+export interface PowerMapOptions {
+  /** The HTML element ID or element reference to mount the map into */
+  container: string | HTMLElement;
+  /** Initial map center as [longitude, latitude] */
+  center?: [number, number];
+  /** Initial zoom level */
+  zoom?: number;
+  /** Minimum zoom level */
+  minZoom?: number;
+  /** Maximum zoom level */
+  maxZoom?: number;
+  /** Map style name: 'th' | 'en' | 'dark' | 'gray' or a custom style URL */
+  style?: 'th' | 'en' | 'dark' | 'gray' | string;
+  /** API Key for map tiles */
+  mapApiKey: string;
+  /** Authentication credentials for services */
+  auth: PowerMapAuthOptions;
+  /** Disable all map interactions (zoom, pan, rotate) — preview mode */
+  previewOnly?: boolean;
+}
+
+export interface MarkerOptions {
+  /** [longitude, latitude] */
+  position: [number, number];
+  /** Marker type */
+  type?: 'start' | 'destination' | 'waypoint' | string;
+  /** Custom image URL */
+  iconUrl?: string;
+  /** Custom hex color for pinpoint marker (e.g. '#ff4444') */
+  color?: string;
+  /** FontAwesome icon class (e.g. 'fas fa-car') */
+  icon?: string;
+  /** Enable marker dragging */
+  draggable?: boolean;
+  /** HTML content or structured popup object */
+  popupContent?: string | { title?: string; body?: string; tag?: string; footer?: string };
+  /** Unique identifier for the marker */
+  id?: string;
+}
+
+export interface MarkerInstance {
+  id: string;
+  position: [number, number];
+  remove(): void;
+  setLngLat(lngLat: [number, number]): this;
+  getLngLat(): { lng: number; lat: number };
+  [key: string]: unknown;
+}
+
+export interface RouteOptions {
+  start: [number, number];
+  destination: [number, number];
+  waypoints?: [number, number][];
+  optimize?: boolean;
+  [key: string]: unknown;
+}
+
+export interface RouteStep {
+  distance: number;
+  distanceStr: string;
+  duration: number;
+  durationStr: string;
+  instruction?: string;
+  [key: string]: unknown;
+}
+
+export interface RouteDetails {
+  distance: number;
+  distanceStr: string;
+  duration: number;
+  durationStr: string;
+  steps: RouteStep[];
+}
+
+export interface RouteSummary {
+  distanceStr: string;
+  durationStr: string;
+}
+
+export interface SearchResult {
+  id?: string;
+  gid?: string;
+  name: string;
+  nameEn?: string;
+  nameTh?: string;
+  address?: string;
+  addressEn?: string;
+  addressTh?: string;
+  position: [number, number];
+  positionLngLat?: [number, number];
+  province?: string;
+  amphoe?: string;
+  tambon?: string;
+  postCode?: string;
+  rawData?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface SearchOptions {
+  location?: [number, number];
+  lang?: 'th' | 'en' | 'auto' | string;
+  [key: string]: unknown;
+}
+
+export interface FlyToOptions {
+  center?: [number, number];
+  zoom?: number;
+  pitch?: number;
+  bearing?: number;
+  speed?: number;
+  curve?: number;
+  [key: string]: unknown;
+}
+
+export interface FitBoundsOptions {
+  padding?: number | { top: number; bottom: number; left: number; right: number };
+  maxZoom?: number;
+  [key: string]: unknown;
+}
+
+export type PowerMapEventName =
+  | 'mapLoaded'
+  | 'mapClick'
+  | 'mapLongClick'
+  | 'markerClick'
+  | 'markerDrag'
+  | 'markerDragEnd'
+  | 'poiClick'
+  | 'routeCalculated'
+  | 'modeChanged'
+  | 'floorChanged'
+  | 'venueChanged'
+  | 'indoorMapLoaded'
+  | 'indoorMapUnloaded'
+  | 'error'
+  | string;
+
+export type PowerMapMode = 'standard' | 'indoor';
+
+export interface SetModeOptions {
+  buildingId?: string;
+  floorId?: string;
+  center?: [number, number];
+  [key: string]: unknown;
+}
+
+// ── IMDF Types ──────────────────────────────────────────────────────────────────
+
+/** OGC IMDF 1.0.0 Feature Types */
+export type IMDFFeatureType =
+  | 'venue' | 'building' | 'level' | 'unit' | 'opening' | 'amenity'
+  | 'anchor' | 'footprint' | 'fixture' | 'section' | 'geofence'
+  | 'kiosk' | 'detail' | 'occupant' | 'address' | 'relationship'
+  | 'pathway';
+
+/** SDK internal kind names */
+export type GeometryKind =
+  | 'venue' | 'building' | 'floor' | 'unit' | 'opening' | 'amenity'
+  | 'anchor' | 'footprint' | 'fixture' | 'section' | 'geofence'
+  | 'kiosk' | 'detail' | 'occupant' | 'address' | 'relationship'
+  | 'beacon' | 'poi' | 'walkway' | 'obstacle';
+
+/** Category visibility toggles */
+export type CategoryType = 'poi' | 'beacon' | 'walkway' | 'obstacle';
+
+/** IMDF LABELS object (i18n) */
+export interface IMDFLabels {
+  [languageCode: string]: string;
+}
+
+// ── Indoor Types ────────────────────────────────────────────────────────────────
+
+export interface VenueInfo {
+  id: string;
+  name: string;
+  category: string;
+  floors: number[];
+  bounds: [[number, number], [number, number]] | null;
+  buildingCount: number;
+}
+
+export interface VenueListItem {
+  id: string;
+  name: string;
+  category: string;
+  feature: object;
+}
+
+export interface FloorInfo {
+  id: string;
+  name: string;
+  shortName: string;
+  ordinal: number;
+  outdoor: boolean;
+  unitCount: number;
+  poiCount: number;
+  beaconCount: number;
+}
+
+export interface BuildingInfo {
+  id: string;
+  name: string;
+  category: string;
+}
+
+export interface LoadIndoorMapOptions {
+  initialFloor?: number;
+  fitBounds?: boolean;
+  fitBoundsOptions?: FitBoundsOptions;
+  animate?: boolean;
+}
+
+export interface LoadIndoorMapResult {
+  venue: object;
+  floors: number[];
+  currentFloor: number;
+}
+
+export interface FloorSwitchOptions {
+  animate?: boolean;
+  duration?: number;
+}
+
+// ── FloorManager ────────────────────────────────────────────────────────────────
+
+export interface FloorManager {
+  /** Set the current floor ordinal with optional animation */
+  setFloor(ordinal: number, options?: FloorSwitchOptions): Promise<FloorManager>;
+  /** Get all unique floor ordinals present in the map */
+  getAvailableFloors(): number[];
+  /** Get the current floor ordinal */
+  getCurrentFloor(): number;
+  /** Set visibility for a category of indoor objects */
+  setCategoryVisible(type: CategoryType, visible: boolean): FloorManager;
+  /** Get the currently active venue feature */
+  getActiveVenue(): object | null;
+  /** List all venue features available in loaded geometry */
+  getVenues(): VenueListItem[];
+  /** Get summary information about the currently active venue */
+  getVenueInfo(): VenueInfo | null;
+  /** Get detailed information about a specific floor */
+  getFloorInfo(ordinal: number): FloorInfo | null;
+  /** List all building features in loaded geometry */
+  getBuildings(): BuildingInfo[];
+}
+
+// ── GeometryQuery ───────────────────────────────────────────────────────────────
+
+export interface GeometryQuery {
+  byKind(kind: GeometryKind): GeometryQuery;
+  byFloor(ordinal: number): GeometryQuery;
+  byType(type: 'Point' | 'Polygon' | 'LineString'): GeometryQuery;
+  where(prop: string, op: 'eq' | 'neq' | 'contains' | 'gt' | 'lt' | 'exists', value?: unknown): GeometryQuery;
+  byFeatureType(featureType: IMDFFeatureType): GeometryQuery;
+  byVenueId(venueId: string): GeometryQuery;
+  byBuildingId(buildingId: string): GeometryQuery;
+  byLevelId(levelId: string): GeometryQuery;
+  toArray(): object[];
+  first(): object | null;
+  count(): number;
+  ids(): string[];
+}
+
+// ── Validation ──────────────────────────────────────────────────────────────────
+
+export interface ValidationError {
+  code: string;
+  message: string;
+  featureId?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationError[];
+}
+
+// ── GeometryManager ─────────────────────────────────────────────────────────────
+
+export interface GeometryManager {
+  query(): GeometryQuery;
+  create(kind: GeometryKind, options?: object): string | null;
+  add(geojson: object): void;
+  update(id: string, patch: object): void;
+  remove(id: string): void;
+  getById(id: string): object | null;
+  getByKind(kind: GeometryKind): object[];
+  getGeoJSON(id: string, options?: { format: 'imdf' | 'standard' }): object | null;
+  export(options?: { format: 'imdf' | 'standard' }): object;
+  import(geojson: object, options?: { format: 'imdf' | 'standard' }): GeometryManager;
+  exportArchive?(): Promise<Blob>;
+  importArchive?(file: Blob | File): Promise<void>;
+  clear(): void;
+}
+
+// ── PowerMap Main Class ─────────────────────────────────────────────────────────
+
+/**
+ * PowerMap SDK Main Class
+ *
+ * Provides a high-level API for map rendering, markers, routing,
+ * indoor navigation, and vehicle simulation.
+ *
+ * @example
+ * const map = new PowerMap({
+ *   container: 'map',
+ *   mapApiKey: 'YOUR_KEY',
+ *   auth: { clientId: '...', clientSecret: '...' }
+ * })
+ * .on('mapLoaded', () => console.log('Ready!'))
+ * .setStyle('dark');
+ */
+export declare class PowerMap {
+  constructor(options: PowerMapOptions);
+
+  // --- Events ---
+  on(event: PowerMapEventName, callback: (...args: unknown[]) => void): this;
+  off(event: PowerMapEventName, callback: (...args: unknown[]) => void): this;
+  onMapLoaded(callback: (data: { map: PowerMap }) => void): this;
+  onClick(callback: (event: unknown) => void): this;
+  onMapLongClick(callback: (event: unknown) => void): this;
+  onMarkerClick(callback: (data: { marker: MarkerInstance; originalEvent: unknown; options: unknown }) => void): this;
+  onPoiClick(callback: (data: { feature: unknown; lngLat: unknown; point: unknown }) => void): this;
+  onMarkerDrag(callback: (data: { marker: MarkerInstance; lngLat: [number, number] }) => void): this;
+  onMarkerDragEnd(callback: (data: { marker: MarkerInstance; lngLat: [number, number] }) => void): this;
+  onRouteCalculated(callback: (route: unknown) => void): this;
+  onError(callback: (error: Error) => void): this;
+
+  // --- Map Style & Mode ---
+  setStyle(name: 'th' | 'en' | 'dark' | 'gray' | string): this;
+  setMode(mode: PowerMapMode, options?: SetModeOptions): this;
+
+  // --- Controls ---
+  setNavigationControl(options: boolean | object): this;
+  setFullscreenControl(options: boolean | object): this;
+
+  // --- Camera ---
+  flyTo(options: FlyToOptions): this;
+  easeTo(options: FlyToOptions): this;
+  fitBounds(bounds: [[number, number], [number, number]], options?: FitBoundsOptions): this;
+  jumpTo(options: FlyToOptions): this;
+  setPitch(pitch: number, animate?: boolean): this;
+  setBearing(bearing: number, animate?: boolean): this;
+  zoomIn(): this;
+  zoomOut(): this;
+  rotateLeft(): this;
+  rotateRight(): this;
+  getCenter(): { lng: number; lat: number };
+  getZoom(): number;
+  getPitch(): number;
+  getBearing(): number;
+
+  // --- Markers ---
+  addMarker(options: MarkerOptions): MarkerInstance;
+  getMarker(id: string): MarkerInstance | null;
+  removeMarker(markerOrId: MarkerInstance | string): this;
+  updatePopup(marker: MarkerInstance, content: string | object): this;
+  clearMarkers(): this;
+
+  // --- Routing ---
+  addRoute(options: RouteOptions): Promise<unknown>;
+  clearRoutes(): this;
+  getRouteDetails(): RouteDetails | null;
+  getRouteSummary(): RouteSummary | null;
+  formatDistance(meters: number): string;
+  formatDuration(seconds: number): string;
+
+  // --- Search ---
+  search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+
+  // --- Layers ---
+  showLayer(layerId: string): Promise<this>;
+  hideLayer(layerId: string): this;
+  toggleLayer(layerId: string): Promise<this>;
+
+  // --- Indoor Venue Selection ---
+  /** Select and activate an indoor venue from already-loaded geometry data */
+  loadIndoorMap(venueId: string, options?: LoadIndoorMapOptions): LoadIndoorMapResult;
+  /** Convenience alias for map.indoor.setFloor() */
+  setFloor(level: number, options?: FloorSwitchOptions): this;
+  /** Exit indoor mode and clear the active venue selection */
+  unloadIndoorMap(): this;
+
+  // --- Managers (advanced access) ---
+  readonly layers: unknown;
+  readonly geometry: GeometryManager;
+  readonly indoor: FloorManager;
+  readonly editor: unknown;
+  debug(): unknown;
+}
+
+// ── IMDF Utilities ──────────────────────────────────────────────────────────────
+
+export declare class IMDFConverter {
+  static MAPPING: Record<GeometryKind, { feature_type: string; category: string }>;
+  static IMDF_CATEGORIES: Record<string, string[]>;
+  static REQUIRED_PROPERTIES: Record<string, string[]>;
+  static toIMDF(featureCollection: object): object;
+  static fromIMDF(imdfCollection: object): object;
+}
+
+export declare class IMDFArchive {
+  static toArchive(featureCollection: object, options?: { JSZip?: unknown }): Promise<Blob>;
+  static fromArchive(archiveData: Blob | File | ArrayBuffer, options?: { JSZip?: unknown }): Promise<object>;
+  static generateManifest(featureCollection: object): object;
+}
+
+export declare class IMDFValidator {
+  static validate(featureCollection: object, options?: { strict?: boolean }): ValidationResult;
+}