@dtechph/wayfinding-core 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,9 @@
 # `@dtechph/wayfinding-core`
 
-Core API client for the Duon Wayfinding SDK. Fetches CMS-configured malls via `GET /v1/sdk/malls` using `x-api-key`.
+Core API client + telemetry for the Duon Wayfinding SDK.
+
+- `GET /v1/sdk/malls` (with `x-api-key`)
+- Batched `POST /v1/sdk/analytics/events` (session, search, location, geofence, …)
 
 ## Install
 
@@ -8,8 +11,6 @@ Core API client for the Duon Wayfinding SDK. Fetches CMS-configured malls via `G
 npm install @dtechph/wayfinding-core
 ```
 
-Requires GitHub Packages auth — see the [root README](../../README.md).
-
 ## Usage
 
 ```typescript
@@ -18,10 +19,17 @@ import { DuonWayfinding } from "@dtechph/wayfinding-core";
 DuonWayfinding.initialize({
   apiBaseUrl: "https://your-backend.example.com",
   apiKey: "duon_sk_live_...",
+  platform: "react-native",
 });
 
 const malls = await DuonWayfinding.fetchMalls();
-const url = DuonWayfinding.getViewerUrl(malls[0]);
+// Situm malls may include situmApiKey / situmBuildingId
+DuonWayfinding.setActiveMall(malls[0]);
+
+// Escape-hatch tracking (native MapView wires these automatically):
+DuonWayfinding.trackSearch({ query: "coffee", resultType: "poi" });
+await DuonWayfinding.flush();
 ```
 
 For React Native / Expo UI components, use [`@dtechph/wayfinding-react-native`](../react-native).
+See the [root README](../../README.md) for Situm vs kiosk auto-track behavior and CMS reporting.

package/dist/client.js

@@ -1,5 +1,6 @@
 import { DuonAuthError, DuonConfigError, DuonForbiddenError, DuonNetworkError, } from "./errors";
 import { mapApiMall } from "./mall";
+import { configureTelemetry, resetTelemetryForTests, startTelemetrySession, } from "./telemetry";
 let config = null;
 const normalizeBaseUrl = (url) => url.replace(/\/$/, "");
 export const initialize = (next) => {
@@ -12,7 +13,14 @@ export const initialize = (next) => {
     config = {
         apiBaseUrl: normalizeBaseUrl(next.apiBaseUrl.trim()),
         apiKey: next.apiKey.trim(),
+        platform: next.platform,
+        sdkVersion: next.sdkVersion,
     };
+    configureTelemetry({
+        platform: next.platform,
+        sdkVersion: next.sdkVersion,
+    });
+    startTelemetrySession();
 };
 export const getConfig = () => {
     if (!config) {
@@ -60,4 +68,5 @@ export const fetchMalls = async (fetchImpl = fetch) => {
 };
 export const resetForTests = () => {
     config = null;
+    resetTelemetryForTests();
 };

package/dist/index.d.ts

@@ -1,10 +1,75 @@
 import { fetchMalls, getConfig, initialize, resetForTests } from "./client";
 import { getViewerUrl } from "./mall";
-export { initialize, fetchMalls, getConfig, resetForTests, getViewerUrl };
+import { endTelemetrySession, flush, getActiveMall, getClientSessionId, setActiveMall, trackEvent, trackGeofenceEnter, trackGeofenceExit, trackLocation, trackLocationBatch, trackMapError, trackMapLoad, trackPoiSelect, trackSearch } from "./telemetry";
+export { initialize, fetchMalls, getConfig, resetForTests, getViewerUrl, setActiveMall, flush, trackEvent, trackSearch, trackLocation, trackLocationBatch, trackGeofenceEnter, trackGeofenceExit, trackPoiSelect, trackMapLoad, trackMapError, endTelemetrySession, getClientSessionId, getActiveMall, };
 export type { DuonMall, DuonWayfindingConfig, MallMapType } from "./types";
+export type { SdkAnalyticsEventType, TrackEventInput, TelemetryPlatform, } from "./telemetry";
 export { DuonError, DuonAuthError, DuonConfigError, DuonForbiddenError, DuonNetworkError, } from "./errors";
 export declare const DuonWayfinding: {
     initialize: (next: import("./types").DuonWayfindingConfig) => void;
     fetchMalls: (fetchImpl?: import("./client").FetchFn) => Promise<import("./types").DuonMall[]>;
     getViewerUrl: (mall: import("./types").DuonMall) => string;
+    setActiveMall: (mall: import("./types").DuonMall) => void;
+    flush: () => Promise<void>;
+    trackEvent: (input: import("./telemetry").TrackEventInput) => void;
+    trackSearch: (input: {
+        query: string;
+        resultType?: string;
+        resultId?: string;
+        resultName?: string;
+        resultCount?: number;
+        buildingId?: string;
+        floorId?: string;
+    }) => void;
+    trackLocation: (input: {
+        x?: number;
+        y?: number;
+        lat?: number;
+        lng?: number;
+        accuracy?: number;
+        floorId?: string;
+        buildingId?: string;
+    }) => void;
+    trackLocationBatch: (samples: Array<{
+        x?: number;
+        y?: number;
+        lat?: number;
+        lng?: number;
+        accuracy?: number;
+        floorId?: string;
+        buildingId?: string;
+        clientTimestamp?: string;
+    }>) => void;
+    trackGeofenceEnter: (input: {
+        geofenceId: string;
+        geofenceName?: string;
+        buildingId?: string;
+        floorId?: string;
+        code?: string;
+    }) => void;
+    trackGeofenceExit: (input: {
+        geofenceId: string;
+        geofenceName?: string;
+        buildingId?: string;
+        floorId?: string;
+        code?: string;
+    }) => void;
+    trackPoiSelect: (input: {
+        poiId: string;
+        poiName?: string;
+        buildingId?: string;
+        floorId?: string;
+        categoryId?: string;
+    }) => void;
+    trackMapLoad: (input?: {
+        buildingId?: string;
+        mapType?: string;
+    }) => void;
+    trackMapError: (input: {
+        message: string;
+        buildingId?: string;
+    }) => void;
+    endTelemetrySession: () => void;
+    getClientSessionId: () => string;
+    getActiveMall: () => import("./types").DuonMall | null;
 };

package/dist/index.js

@@ -1,9 +1,24 @@
 import { fetchMalls, getConfig, initialize, resetForTests } from "./client";
 import { getViewerUrl } from "./mall";
-export { initialize, fetchMalls, getConfig, resetForTests, getViewerUrl };
+import { endTelemetrySession, flush, getActiveMall, getClientSessionId, setActiveMall, trackEvent, trackGeofenceEnter, trackGeofenceExit, trackLocation, trackLocationBatch, trackMapError, trackMapLoad, trackPoiSelect, trackSearch, } from "./telemetry";
+export { initialize, fetchMalls, getConfig, resetForTests, getViewerUrl, setActiveMall, flush, trackEvent, trackSearch, trackLocation, trackLocationBatch, trackGeofenceEnter, trackGeofenceExit, trackPoiSelect, trackMapLoad, trackMapError, endTelemetrySession, getClientSessionId, getActiveMall, };
 export { DuonError, DuonAuthError, DuonConfigError, DuonForbiddenError, DuonNetworkError, } from "./errors";
 export const DuonWayfinding = {
     initialize,
     fetchMalls,
     getViewerUrl,
+    setActiveMall,
+    flush,
+    trackEvent,
+    trackSearch,
+    trackLocation,
+    trackLocationBatch,
+    trackGeofenceEnter,
+    trackGeofenceExit,
+    trackPoiSelect,
+    trackMapLoad,
+    trackMapError,
+    endTelemetrySession,
+    getClientSessionId,
+    getActiveMall,
 };

package/dist/mall.js

@@ -12,6 +12,10 @@ export const mapApiMall = (raw) => {
         mapEmbedUrl: raw.map_embed_url,
         latitude: raw.latitude,
         longitude: raw.longitude,
+        situmApiKey: raw.situm_api_key,
+        situmBuildingId: raw.situm_building_id
+            ? String(raw.situm_building_id)
+            : undefined,
     };
 };
 export const getViewerUrl = (mall) => mall.viewerUrl;

package/dist/telemetry.d.ts

@@ -0,0 +1,82 @@
+import type { DuonMall } from "./types";
+export type SdkAnalyticsEventType = "session_start" | "session_end" | "mall_selected" | "map_load" | "map_error" | "search" | "poi_select" | "location_sample" | "geofence_enter" | "geofence_exit";
+export interface TrackEventInput {
+    type: SdkAnalyticsEventType;
+    buildingId?: string;
+    mallId?: string;
+    floorId?: string;
+    payload?: Record<string, unknown>;
+    clientTimestamp?: string;
+}
+export type TelemetryPlatform = "react-native" | "flutter" | "web" | string;
+export declare const configureTelemetry: (options: {
+    platform?: TelemetryPlatform;
+    sdkVersion?: string;
+    fetchImpl?: typeof fetch;
+}) => void;
+export declare const getClientSessionId: () => string;
+export declare const getActiveMall: () => DuonMall | null;
+/** Call from initialize — starts anonymous session + session_start event. */
+export declare const startTelemetrySession: () => void;
+export declare const endTelemetrySession: () => void;
+export declare const setActiveMall: (mall: DuonMall) => void;
+export declare const trackEvent: (input: TrackEventInput) => void;
+export declare const trackSearch: (input: {
+    query: string;
+    resultType?: string;
+    resultId?: string;
+    resultName?: string;
+    resultCount?: number;
+    buildingId?: string;
+    floorId?: string;
+}) => void;
+export declare const trackLocation: (input: {
+    x?: number;
+    y?: number;
+    lat?: number;
+    lng?: number;
+    accuracy?: number;
+    floorId?: string;
+    buildingId?: string;
+}) => void;
+export declare const trackLocationBatch: (samples: Array<{
+    x?: number;
+    y?: number;
+    lat?: number;
+    lng?: number;
+    accuracy?: number;
+    floorId?: string;
+    buildingId?: string;
+    clientTimestamp?: string;
+}>) => void;
+export declare const trackGeofenceEnter: (input: {
+    geofenceId: string;
+    geofenceName?: string;
+    buildingId?: string;
+    floorId?: string;
+    code?: string;
+}) => void;
+export declare const trackGeofenceExit: (input: {
+    geofenceId: string;
+    geofenceName?: string;
+    buildingId?: string;
+    floorId?: string;
+    code?: string;
+}) => void;
+export declare const trackPoiSelect: (input: {
+    poiId: string;
+    poiName?: string;
+    buildingId?: string;
+    floorId?: string;
+    categoryId?: string;
+}) => void;
+export declare const trackMapLoad: (input?: {
+    buildingId?: string;
+    mapType?: string;
+}) => void;
+export declare const trackMapError: (input: {
+    message: string;
+    buildingId?: string;
+}) => void;
+export declare const flush: () => Promise<void>;
+export declare const resetTelemetryForTests: () => void;

package/dist/telemetry.js

@@ -0,0 +1,255 @@
+import { getConfig } from "./client";
+const FLUSH_INTERVAL_MS = 5000;
+const MAX_QUEUE = 100;
+const LOCATION_MIN_INTERVAL_MS = 1000;
+let clientSessionId = null;
+let platform = "web";
+let sdkVersion = "0.2.0";
+let queue = [];
+let flushTimer = null;
+let flushing = false;
+let lastLocationAt = 0;
+let fetchImpl = fetch;
+let activeMall = null;
+let sessionStarted = false;
+const uuid = () => {
+    if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+        return crypto.randomUUID();
+    }
+    return `sess-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+};
+const ensureSession = () => {
+    if (!clientSessionId) {
+        clientSessionId = uuid();
+    }
+    return clientSessionId;
+};
+const startFlushTimer = () => {
+    if (flushTimer)
+        return;
+    flushTimer = setInterval(() => {
+        void flush();
+    }, FLUSH_INTERVAL_MS);
+};
+export const configureTelemetry = (options) => {
+    if (options.platform)
+        platform = options.platform;
+    if (options.sdkVersion)
+        sdkVersion = options.sdkVersion;
+    if (options.fetchImpl)
+        fetchImpl = options.fetchImpl;
+};
+export const getClientSessionId = () => ensureSession();
+export const getActiveMall = () => activeMall;
+/** Call from initialize — starts anonymous session + session_start event. */
+export const startTelemetrySession = () => {
+    ensureSession();
+    startFlushTimer();
+    if (!sessionStarted) {
+        sessionStarted = true;
+        enqueue({ type: "session_start", payload: {} });
+    }
+};
+export const endTelemetrySession = () => {
+    enqueue({ type: "session_end", payload: {} });
+    void flush();
+    sessionStarted = false;
+};
+export const setActiveMall = (mall) => {
+    activeMall = mall;
+    enqueue({
+        type: "mall_selected",
+        buildingId: mall.buildingId,
+        payload: {
+            mapType: mall.mapType,
+            name: mall.name,
+            viewerHost: (() => {
+                try {
+                    return new URL(mall.viewerUrl).host;
+                }
+                catch {
+                    return undefined;
+                }
+            })(),
+        },
+    });
+};
+const enqueue = (input) => {
+    ensureSession();
+    startFlushTimer();
+    const buildingId = input.buildingId ?? activeMall?.buildingId;
+    queue.push({
+        type: input.type,
+        building_id: buildingId,
+        mall_id: input.mallId,
+        floor_id: input.floorId,
+        payload: input.payload ?? {},
+        client_timestamp: input.clientTimestamp ?? new Date().toISOString(),
+    });
+    if (queue.length >= MAX_QUEUE) {
+        void flush();
+    }
+};
+export const trackEvent = (input) => {
+    enqueue(input);
+};
+export const trackSearch = (input) => {
+    enqueue({
+        type: "search",
+        buildingId: input.buildingId,
+        floorId: input.floorId,
+        payload: {
+            query: input.query,
+            resultType: input.resultType ?? "unknown",
+            resultId: input.resultId,
+            resultName: input.resultName,
+            resultCount: input.resultCount,
+        },
+    });
+};
+export const trackLocation = (input) => {
+    const now = Date.now();
+    if (now - lastLocationAt < LOCATION_MIN_INTERVAL_MS)
+        return;
+    lastLocationAt = now;
+    enqueue({
+        type: "location_sample",
+        buildingId: input.buildingId,
+        floorId: input.floorId,
+        payload: {
+            x: input.x,
+            y: input.y,
+            lat: input.lat,
+            lng: input.lng,
+            accuracy: input.accuracy,
+            floorId: input.floorId,
+            buildingId: input.buildingId,
+        },
+    });
+};
+export const trackLocationBatch = (samples) => {
+    for (const s of samples) {
+        enqueue({
+            type: "location_sample",
+            buildingId: s.buildingId,
+            floorId: s.floorId,
+            clientTimestamp: s.clientTimestamp,
+            payload: {
+                x: s.x,
+                y: s.y,
+                lat: s.lat,
+                lng: s.lng,
+                accuracy: s.accuracy,
+                floorId: s.floorId,
+                buildingId: s.buildingId,
+            },
+        });
+    }
+};
+export const trackGeofenceEnter = (input) => {
+    enqueue({
+        type: "geofence_enter",
+        buildingId: input.buildingId,
+        floorId: input.floorId,
+        payload: {
+            geofenceId: input.geofenceId,
+            geofenceName: input.geofenceName,
+            buildingId: input.buildingId,
+            floorId: input.floorId,
+            code: input.code,
+        },
+    });
+};
+export const trackGeofenceExit = (input) => {
+    enqueue({
+        type: "geofence_exit",
+        buildingId: input.buildingId,
+        floorId: input.floorId,
+        payload: {
+            geofenceId: input.geofenceId,
+            geofenceName: input.geofenceName,
+            buildingId: input.buildingId,
+            floorId: input.floorId,
+            code: input.code,
+        },
+    });
+};
+export const trackPoiSelect = (input) => {
+    enqueue({
+        type: "poi_select",
+        buildingId: input.buildingId,
+        floorId: input.floorId,
+        payload: {
+            resultId: input.poiId,
+            resultName: input.poiName,
+            resultType: "poi",
+            categoryId: input.categoryId,
+        },
+    });
+};
+export const trackMapLoad = (input) => {
+    enqueue({
+        type: "map_load",
+        buildingId: input?.buildingId,
+        payload: { mapType: input?.mapType },
+    });
+};
+export const trackMapError = (input) => {
+    enqueue({
+        type: "map_error",
+        buildingId: input.buildingId,
+        payload: { message: input.message },
+    });
+};
+export const flush = async () => {
+    if (flushing || queue.length === 0)
+        return;
+    let apiBaseUrl;
+    let apiKey;
+    try {
+        ({ apiBaseUrl, apiKey } = getConfig());
+    }
+    catch {
+        return;
+    }
+    flushing = true;
+    const batch = queue.splice(0, MAX_QUEUE);
+    try {
+        const response = await fetchImpl(`${apiBaseUrl}/v1/sdk/analytics/events`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-api-key": apiKey,
+            },
+            body: JSON.stringify({
+                client_session_id: ensureSession(),
+                platform,
+                sdk_version: sdkVersion,
+                events: batch,
+            }),
+        });
+        if (!response.ok) {
+            // Put back on failure (best-effort)
+            queue.unshift(...batch);
+        }
+    }
+    catch {
+        queue.unshift(...batch);
+    }
+    finally {
+        flushing = false;
+    }
+};
+export const resetTelemetryForTests = () => {
+    clientSessionId = null;
+    queue = [];
+    flushing = false;
+    lastLocationAt = 0;
+    activeMall = null;
+    sessionStarted = false;
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+};

package/dist/types.d.ts

@@ -7,10 +7,16 @@ export interface DuonMall {
     mapEmbedUrl?: string;
     latitude?: number;
     longitude?: number;
+    /** Present for Situm malls from authenticated SDK mall list. */
+    situmApiKey?: string;
+    situmBuildingId?: string;
 }
 export interface DuonWayfindingConfig {
     apiBaseUrl: string;
     apiKey: string;
+    /** Optional override; defaults by platform package. */
+    platform?: string;
+    sdkVersion?: string;
 }
 export interface MallsApiResponse {
     status: number;
@@ -22,5 +28,7 @@ export interface MallsApiResponse {
         map_embed_url?: string;
         latitude?: number;
         longitude?: number;
+        situm_api_key?: string;
+        situm_building_id?: string;
     }>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtechph/wayfinding-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Duon Wayfinding SDK — core API client for CMS-driven mall maps",
   "license": "UNLICENSED",
   "author": "dtechph",