react-native-pointr 10.7.1 → 10.9.0

package/src/hooks/index.ts

@@ -7,3 +7,12 @@ export {
   usePointrSiteClick,
 } from './usePointrEvents';
 export { usePointrGeofences } from './usePointrGeofences';
+export { usePointrData } from './usePointrData';
+export { usePointrSite } from './usePointrSite';
+export {
+  usePointrDataManagerStart,
+  usePointrDataManagerCompleteAll,
+  usePointrDataManagerBeginProcessing,
+  usePointrDataManagerEndProcessing,
+  usePointrDataManagerReady,
+} from './usePointrDataEvents';

package/src/hooks/usePointrData.ts

@@ -0,0 +1,94 @@
+import { useEffect, useState, useCallback } from 'react';
+import {
+  loadDataForSite,
+  isSiteContentReady,
+} from '../managers/PTRDataManager';
+import { pointrSdk } from '../api/PointrSdk';
+import type { PTRDataManagerReadyEvent } from '../types/events';
+
+/**
+ * Hook that manages a site's data lifecycle.
+ *
+ * It demonstrates the {@link loadDataForSite} and {@link isSiteContentReady}
+ * data-manager methods: on mount it triggers data management for the site and
+ * checks the current readiness, then keeps `isReady` in sync by listening for
+ * the `OnDataManagerReadyForSite` event emitted once all data is available.
+ *
+ * @param siteId - Site identifier to manage data for
+ * @param options - Optional flags forwarded to the data manager
+ * @param options.shouldRespectCachePolicy - When `true` (default), respects the
+ * internal cache; when `false`, forces a fresh data update.
+ * @param options.isExternalIdentifier - When `false` (default), `siteId` is the
+ * internal identifier; when `true`, it is the external identifier.
+ * @returns `{ isReady, loading, error, reload }`
+ *
+ * @example
+ * ```tsx
+ * const { isReady, loading, reload } = usePointrData(SITE_ID);
+ *
+ * if (loading) return <Spinner />;
+ * return isReady ? <Map siteId={SITE_ID} /> : <Button onPress={reload} title="Load" />;
+ * ```
+ */
+export function usePointrData(
+  siteId?: string,
+  options?: {
+    shouldRespectCachePolicy?: boolean;
+    isExternalIdentifier?: boolean;
+  }
+) {
+  const [isReady, setIsReady] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const shouldRespectCachePolicy = options?.shouldRespectCachePolicy ?? true;
+  const isExternalIdentifier = options?.isExternalIdentifier ?? false;
+
+  const load = useCallback(
+    async (id: string) => {
+      if (!id) return;
+      setLoading(true);
+      setError(null);
+      try {
+        await loadDataForSite(id, shouldRespectCachePolicy, isExternalIdentifier);
+        const ready = await isSiteContentReady(id, isExternalIdentifier);
+        setIsReady(ready);
+      } catch (err) {
+        setError(err as Error);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [shouldRespectCachePolicy, isExternalIdentifier]
+  );
+
+  // Trigger data management whenever the target site changes.
+  useEffect(() => {
+    if (siteId) {
+      load(siteId);
+    }
+  }, [siteId, load]);
+
+  // Keep `isReady` in sync once the data manager reports the site is ready.
+  useEffect(() => {
+    if (!siteId) return;
+    const subscription = pointrSdk.onDataManagerReady(
+      (event: PTRDataManagerReadyEvent) => {
+        const readySiteId = isExternalIdentifier
+          ? event.site.externalIdentifier
+          : event.site.identifier;
+        if (readySiteId === siteId) {
+          setIsReady(true);
+        }
+      }
+    );
+    return () => subscription.remove();
+  }, [siteId, isExternalIdentifier]);
+
+  return {
+    isReady,
+    loading,
+    error,
+    reload: () => siteId && load(siteId),
+  };
+}

package/src/hooks/usePointrDataEvents.ts

@@ -0,0 +1,74 @@
+import { useEffect } from 'react';
+import { pointrSdk } from '../api/PointrSdk';
+import type {
+  PTRDataManagerStartEvent,
+  PTRDataManagerCompleteAllEvent,
+  PTRDataManagerBeginProcessingEvent,
+  PTRDataManagerEndProcessingEvent,
+  PTRDataManagerReadyEvent,
+} from '../types/events';
+
+/**
+ * Hook to listen for data-management-start events.
+ * @param callback - Called when the data manager starts managing a site's data
+ */
+export function usePointrDataManagerStart(
+  callback: (event: PTRDataManagerStartEvent) => void
+) {
+  useEffect(() => {
+    const subscription = pointrSdk.onDataManagerStart(callback);
+    return () => subscription.remove();
+  }, [callback]);
+}
+
+/**
+ * Hook to listen for data-management-complete-all events.
+ * @param callback - Called when all data processing for a site completes
+ */
+export function usePointrDataManagerCompleteAll(
+  callback: (event: PTRDataManagerCompleteAllEvent) => void
+) {
+  useEffect(() => {
+    const subscription = pointrSdk.onDataManagerCompleteAll(callback);
+    return () => subscription.remove();
+  }, [callback]);
+}
+
+/**
+ * Hook to listen for begin-processing events for a specific data type.
+ * @param callback - Called when a specific data type starts being processed
+ */
+export function usePointrDataManagerBeginProcessing(
+  callback: (event: PTRDataManagerBeginProcessingEvent) => void
+) {
+  useEffect(() => {
+    const subscription = pointrSdk.onDataManagerBeginProcessing(callback);
+    return () => subscription.remove();
+  }, [callback]);
+}
+
+/**
+ * Hook to listen for end-processing events for a specific data type.
+ * @param callback - Called when a specific data type finishes being processed
+ */
+export function usePointrDataManagerEndProcessing(
+  callback: (event: PTRDataManagerEndProcessingEvent) => void
+) {
+  useEffect(() => {
+    const subscription = pointrSdk.onDataManagerEndProcessing(callback);
+    return () => subscription.remove();
+  }, [callback]);
+}
+
+/**
+ * Hook to listen for site-ready events (all data available to display a site).
+ * @param callback - Called when a site becomes ready to display
+ */
+export function usePointrDataManagerReady(
+  callback: (event: PTRDataManagerReadyEvent) => void
+) {
+  useEffect(() => {
+    const subscription = pointrSdk.onDataManagerReady(callback);
+    return () => subscription.remove();
+  }, [callback]);
+}

package/src/hooks/usePointrSite.ts

@@ -0,0 +1,73 @@
+import { useEffect, useState, useCallback } from 'react';
+import { getSite, getBuildings } from '../managers/PTRSiteManager';
+import type { PTRSite, PTRBuilding } from '../types/PTRSite';
+
+/**
+ * Hook that loads a site and its buildings.
+ *
+ * It demonstrates the {@link getSite} and {@link getBuildings} site-manager
+ * methods: whenever the target site changes it fetches the site and, if found,
+ * its buildings.
+ *
+ * @param siteId - Site identifier to load
+ * @param options - Optional flags forwarded to the site manager
+ * @param options.isExternalIdentifier - When `false` (default), `siteId` is the
+ * internal identifier; when `true`, it is the external identifier.
+ * @returns `{ site, buildings, loading, error, refetch }`
+ *
+ * @example
+ * ```tsx
+ * const { site, buildings, loading } = usePointrSite(SITE_ID);
+ *
+ * if (loading) return <Spinner />;
+ * return <Text>{site?.name} — {buildings.length} buildings</Text>;
+ * ```
+ */
+export function usePointrSite(
+  siteId?: string,
+  options?: { isExternalIdentifier?: boolean }
+) {
+  const [site, setSite] = useState<PTRSite | null>(null);
+  const [buildings, setBuildings] = useState<PTRBuilding[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const isExternalIdentifier = options?.isExternalIdentifier ?? false;
+
+  const fetchSite = useCallback(
+    async (id: string) => {
+      if (!id) return;
+      setLoading(true);
+      setError(null);
+      try {
+        const fetchedSite = await getSite(id, isExternalIdentifier);
+        setSite(fetchedSite);
+        if (fetchedSite) {
+          const fetchedBuildings = await getBuildings(id, isExternalIdentifier);
+          setBuildings(fetchedBuildings);
+        } else {
+          setBuildings([]);
+        }
+      } catch (err) {
+        setError(err as Error);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [isExternalIdentifier]
+  );
+
+  useEffect(() => {
+    if (siteId) {
+      fetchSite(siteId);
+    }
+  }, [siteId, fetchSite]);
+
+  return {
+    site,
+    buildings,
+    loading,
+    error,
+    refetch: () => siteId && fetchSite(siteId),
+  };
+}

package/src/index.tsx

@@ -41,11 +41,15 @@ export {
   PTRActionParamKeys,
   PTRSdkConfigKeys,
   PTRCommandNames,
+  PTREventPayloadKeys,
+  PTRModelKeys,
 } from './constants';
 export type {
   PTRActionParamKey,
   PTRSdkConfigKey,
   PTRCommandName,
+  PTREventPayloadKey,
+  PTRModelKey,
 } from './constants';
 
 // ─── React Hooks ───────────────────────────────────────────────────────────────
@@ -57,6 +61,13 @@ export {
   usePointrBuildingClick,
   usePointrSiteClick,
   usePointrGeofences,
+  usePointrData,
+  usePointrSite,
+  usePointrDataManagerStart,
+  usePointrDataManagerCompleteAll,
+  usePointrDataManagerBeginProcessing,
+  usePointrDataManagerEndProcessing,
+  usePointrDataManagerReady,
 } from './hooks';
 
 // ─── Components ────────────────────────────────────────────────────────────────
@@ -91,6 +102,12 @@ export type {
   PTRGeofence,
   PTRGeofenceNotification,
   PTRMapCommandResponse,
+  PTRDataType,
+  PTRDataManagerStartEvent,
+  PTRDataManagerCompleteAllEvent,
+  PTRDataManagerBeginProcessingEvent,
+  PTRDataManagerEndProcessingEvent,
+  PTRDataManagerReadyEvent,
 } from './types/events';
 
 export { PTRGeofenceEventType } from './types/events';

package/src/managers/PTRDataManager.ts

@@ -0,0 +1,57 @@
+import { NativeModules } from 'react-native';
+
+const { PTRNativeLibrary } = NativeModules;
+
+/**
+ * Start data management for a specific site if the data is not already present.
+ * @param siteId - The identifier of the site
+ * @param shouldRespectCachePolicy - When `true` (default), waits until the
+ * cache expires if data is already present. When `false`, ignores the internal
+ * cache and triggers a data update immediately.
+ * @param isExternalIdentifier - When `false` (default), `siteId` is treated as
+ * the site's internal identifier. When `true`, it is treated as the external
+ * identifier.
+ * @returns Promise that resolves once data management has been triggered
+ * @throws Error if the site is not found or if the operation fails
+ */
+export async function loadDataForSite(
+  siteId: string,
+  shouldRespectCachePolicy: boolean = true,
+  isExternalIdentifier: boolean = false
+): Promise<void> {
+  try {
+    await PTRNativeLibrary.loadDataForSite(
+      siteId,
+      shouldRespectCachePolicy,
+      isExternalIdentifier
+    );
+  } catch (error) {
+    console.error('Failed to load data for site:', error);
+    throw error;
+  }
+}
+
+/**
+ * Check whether all data is ready for use for a given site.
+ * @param siteId - The identifier of the site
+ * @param isExternalIdentifier - When `false` (default), `siteId` is treated as
+ * the site's internal identifier. When `true`, it is treated as the external
+ * identifier.
+ * @returns Promise that resolves with `true` if the site content is ready
+ * @throws Error if the site is not found or if the operation fails
+ */
+export async function isSiteContentReady(
+  siteId: string,
+  isExternalIdentifier: boolean = false
+): Promise<boolean> {
+  try {
+    const isReady = await PTRNativeLibrary.isSiteContentReady(
+      siteId,
+      isExternalIdentifier
+    );
+    return isReady as boolean;
+  } catch (error) {
+    console.error('Failed to check site content readiness:', error);
+    throw error;
+  }
+}

package/src/managers/PTRSiteManager.ts

@@ -0,0 +1,143 @@
+import { NativeModules } from 'react-native';
+import type { PTRSite, PTRBuilding } from '../types/PTRSite';
+
+const { PTRNativeLibrary } = NativeModules;
+
+/**
+ * Get the name of the client.
+ * @returns Promise that resolves with the client name
+ * @throws Error if the operation fails
+ */
+export async function getClientName(): Promise<string> {
+  try {
+    const clientName = await PTRNativeLibrary.getClientName();
+    return clientName as string;
+  } catch (error) {
+    console.error('Failed to get client name:', error);
+    throw error;
+  }
+}
+
+/**
+ * Get all available sites.
+ * @returns Promise that resolves with an array of sites
+ * @throws Error if the operation fails
+ */
+export async function getSites(): Promise<PTRSite[]> {
+  try {
+    const sites = await PTRNativeLibrary.getSites();
+    return sites as PTRSite[];
+  } catch (error) {
+    console.error('Failed to get sites:', error);
+    throw error;
+  }
+}
+
+/**
+ * Get a single site by its identifier.
+ * @param siteId - The identifier of the site
+ * @param isExternalIdentifier - When `false` (default), `siteId` is treated as
+ * the internal identifier. When `true`, it is treated as the external identifier.
+ * @returns Promise that resolves with the site, or `null` if not found
+ * @throws Error if the operation fails
+ */
+export async function getSite(
+  siteId: string,
+  isExternalIdentifier: boolean = false
+): Promise<PTRSite | null> {
+  try {
+    const site = await PTRNativeLibrary.getSite(siteId, isExternalIdentifier);
+    return (site as PTRSite) ?? null;
+  } catch (error) {
+    console.error('Failed to get site:', error);
+    throw error;
+  }
+}
+
+/**
+ * Get all buildings for a site.
+ * @param siteId - The identifier of the site
+ * @param isExternalIdentifier - When `false` (default), `siteId` is treated as
+ * the internal identifier. When `true`, it is treated as the external identifier.
+ * @returns Promise that resolves with an array of buildings
+ * @throws Error if the site is not found or if the operation fails
+ */
+export async function getBuildings(
+  siteId: string,
+  isExternalIdentifier: boolean = false
+): Promise<PTRBuilding[]> {
+  try {
+    const buildings = await PTRNativeLibrary.getSiteBuildings(
+      siteId,
+      isExternalIdentifier
+    );
+    return buildings as PTRBuilding[];
+  } catch (error) {
+    console.error('Failed to get buildings:', error);
+    throw error;
+  }
+}
+
+/**
+ * Get a single building within a site by its identifier.
+ * @param siteId - The identifier of the site containing the building
+ * @param buildingId - The identifier of the building
+ * @param isExternalIdentifier - When `false` (default), both identifiers are
+ * treated as internal identifiers. When `true`, they are treated as external
+ * identifiers.
+ * @returns Promise that resolves with the building, or `null` if not found
+ * @throws Error if the operation fails
+ */
+export async function getBuilding(
+  siteId: string,
+  buildingId: string,
+  isExternalIdentifier: boolean = false
+): Promise<PTRBuilding | null> {
+  try {
+    const building = await PTRNativeLibrary.getBuilding(
+      siteId,
+      buildingId,
+      isExternalIdentifier
+    );
+    return (building as PTRBuilding) ?? null;
+  } catch (error) {
+    console.error('Failed to get building:', error);
+    throw error;
+  }
+}
+
+/**
+ * Get the map data URL for a site.
+ * @param siteId - The identifier of the site
+ * @param isExternalIdentifier - When `false` (default), `siteId` is treated as
+ * the internal identifier. When `true`, it is treated as the external identifier.
+ * @returns Promise that resolves with the map URL, or `null` if unavailable
+ * @throws Error if the site is not found or if the operation fails
+ */
+export async function getMapUrl(
+  siteId: string,
+  isExternalIdentifier: boolean = false
+): Promise<string | null> {
+  try {
+    const mapUrl = await PTRNativeLibrary.getMapUrl(siteId, isExternalIdentifier);
+    return (mapUrl as string) ?? null;
+  } catch (error) {
+    console.error('Failed to get map URL:', error);
+    throw error;
+  }
+}
+
+/**
+ * Get the URL for the map style JSON.
+ * @returns Promise that resolves with the style JSON URL, or `null` if unavailable
+ * @throws Error if the operation fails
+ */
+export async function getStyleJsonUrl(): Promise<string | null> {
+  try {
+    const styleUrl = await PTRNativeLibrary.getStyleJsonUrl();
+    return (styleUrl as string) ?? null;
+  } catch (error) {
+    console.error('Failed to get style JSON URL:', error);
+    throw error;
+  }
+}

package/src/types/events.ts

@@ -4,6 +4,7 @@
  */
 
 import type { PTRPosition } from './PTRPosition';
+import type { PTRSite } from './PTRSite';
 
 /**
  * Position event payload
@@ -93,6 +94,78 @@ export interface PTRGeofenceEvent {
   readonly timestamp?: number;
 }
 
+/**
+ * Type of data managed by the Pointr SDK data manager
+ */
+export interface PTRDataType {
+  /** Numeric value of the data type */
+  readonly value: number;
+  /** Human-readable name of the data type (e.g. "Poi", "Maps") */
+  readonly name: string;
+}
+
+/**
+ * Emitted when the data manager starts data management for a site.
+ */
+export interface PTRDataManagerStartEvent {
+  /** Site the data belongs to */
+  readonly site: PTRSite;
+  /** Whether the data is from the server (online) or a local bundle (offline) */
+  readonly isOnlineData: boolean;
+}
+
+/**
+ * Emitted when the data manager completes all processing for a site.
+ */
+export interface PTRDataManagerCompleteAllEvent {
+  /** Site the data belongs to */
+  readonly site: PTRSite;
+  /** Whether all updates succeeded */
+  readonly isSuccessful: boolean;
+  /** Whether the data is from the server (online) or a local bundle (offline) */
+  readonly isOnlineData: boolean;
+  /** Error messages, if any */
+  readonly errors: string[];
+}
+
+/**
+ * Emitted when the data manager begins processing a specific data type.
+ */
+export interface PTRDataManagerBeginProcessingEvent {
+  /** Site the data belongs to */
+  readonly site: PTRSite;
+  /** Type of data being processed (absent for global data) */
+  readonly dataType?: PTRDataType;
+  /** Whether the data is from the server (online) or a local bundle (offline) */
+  readonly isOnlineData: boolean;
+}
+
+/**
+ * Emitted when the data manager ends processing a specific data type.
+ */
+export interface PTRDataManagerEndProcessingEvent {
+  /** Site the data belongs to */
+  readonly site: PTRSite;
+  /** Type of data that was processed (absent for global data) */
+  readonly dataType?: PTRDataType;
+  /** Whether the data is from the server (online) or a local bundle (offline) */
+  readonly isOnlineData: boolean;
+  /** Whether the update succeeded */
+  readonly isSuccessful: boolean;
+  /** Error messages, if any */
+  readonly errors: string[];
+}
+
+/**
+ * Emitted when all data needed to display a site is available.
+ * @remarks This does not mean the data is the latest, only that there is valid
+ * data to show. Both raster maps and tile maps are considered for this check.
+ */
+export interface PTRDataManagerReadyEvent {
+  /** Site the data belongs to */
+  readonly site: PTRSite;
+}
+
 /**
  * Map command response payload
  */