hypertrack-sdk-react-native 10.0.3 → 11.0.0

package/src/HyperTrack/HyperTrack.ts

@@ -1,23 +1,30 @@
-import { NativeModules, Platform, NativeEventEmitter } from 'react-native';
+import {
+  NativeModules,
+  Platform,
+  NativeEventEmitter,
+  EmitterSubscription,
+} from 'react-native';
 import { HyperTrackError } from './data_types/HyperTrackError';
 import type { IsAvailable } from './data_types/internal/IsAvailable';
 import type { IsTracking } from './data_types/internal/IsTracking';
 import type { Location } from './data_types/Location';
 import type { LocationError } from './data_types/LocationError';
-import type { SdkInitParams } from './data_types/SdkInitParams';
 import type { DeviceId } from './data_types/internal/DeviceId';
 import type { GeotagData } from './data_types/internal/GeotagData';
-import type { DeviceName } from './data_types/internal/DeviceName';
+import type { Name } from './data_types/internal/Name';
 import type { HyperTrackErrorInternal } from './data_types/internal/HyperTrackErrorInternal';
-import type { Result } from './data_types/Result';
 import type { LocationWithDeviation } from './data_types/LocationWithDeviation';
 import type { LocationErrorInternal } from './data_types/internal/LocationErrorInternal';
+import type { Result } from './data_types/Result';
 import type { LocationInternal } from './data_types/internal/LocationInternal';
 import type { LocationWithDeviationInternal } from './data_types/internal/LocationWithDeviationInternal';
+import type { Metadata } from './data_types/internal/Metadata';
 
-const EVENT_TRACKING = 'onTrackingChanged';
-const EVENT_AVAILABILITY = 'onAvailabilityChanged';
-const EVENT_ERROR = 'onError';
+const EVENT_ERRORS = 'errors';
+const EVENT_IS_AVAILABLE = 'isAvailable';
+const EVENT_IS_TRACKING = 'isTracking';
+const EVENT_LOCATE = 'locate';
+const EVENT_LOCATION = 'location';
 
 const LINKING_ERROR =
   `The package 'hypertrack-sdk-react-native' doesn't seem to be linked. Make sure: \n\n` +
@@ -39,193 +46,234 @@ const HyperTrackSdk = NativeModules.HyperTrackReactNativePlugin
 const EventEmitter = new NativeEventEmitter(HyperTrackSdk);
 
 export default class HyperTrack {
-  private constructor() {
-    return this;
-  }
+  private static locateSubscription: EmitterSubscription | undefined;
 
   /**
-   * Creates an SDK instance
+   * Adds a new geotag
    *
-   * @param publishableKey publishable key provided in HyperTrack’s dashboard setup page
-   * @param sdkInitParams
-   * @returns HyperTrack instance
+   * @param {Object} data - Geotad data JSON
+   * @returns current location if success or LocationError if failure
    */
-  static async initialize(
-    publishableKey: string,
-    sdkInitParams: SdkInitParams = {}
-  ): Promise<HyperTrack> {
-    try {
-      await HyperTrackSdk.initializeSdk({
-        publishableKey,
-        loggingEnabled: sdkInitParams.loggingEnabled ?? false,
-        allowMockLocations: sdkInitParams.allowMockLocations ?? false,
-        requireBackgroundTrackingPermission:
-          sdkInitParams.requireBackgroundTrackingPermission ?? false,
-        automaticallyRequestPermissions:
-          sdkInitParams.automaticallyRequestPermissions ?? true,
-      });
-      return new HyperTrack();
-    } catch (error: any) {
-      throw error;
+  static async addGeotag(
+    data: Object
+  ): Promise<Result<Location, LocationError>>;
+
+  /**
+   * Adds a new geotag with expected location
+   *
+   * @param {Object} data - Geotad data JSON
+   * @param {Location} expectedLocation - Expected location
+   * @returns location with deviation if success or LocationError if failure
+   */
+  static async addGeotag(
+    data: Object,
+    expectedLocation: Location
+  ): Promise<Result<LocationWithDeviation, LocationError>>;
+
+  static async addGeotag(
+    ...args: any[]
+  ): Promise<Result<Location | LocationWithDeviation, LocationError>> {
+    if (args.length === 1 && typeof args[0] === 'object') {
+      return HyperTrackSdk.addGeotag({
+        data: args[0],
+        expectedLocation: undefined,
+      } as GeotagData).then(
+        (locationResponse: Result<LocationInternal, LocationErrorInternal>) => {
+          return this.deserializeLocationResponse(locationResponse);
+        }
+      );
+    } else if (
+      args.length === 2 &&
+      typeof args[0] === 'object' &&
+      HyperTrack.isLocation(args[1])
+    ) {
+      let expectedLocation = args[1] as Location;
+      return HyperTrackSdk.addGeotag({
+        data: args[0],
+        expectedLocation: {
+          type: 'location',
+          value: {
+            latitude: expectedLocation.latitude,
+            longitude: expectedLocation.longitude,
+          },
+        } as LocationInternal,
+      } as GeotagData).then(
+        (
+          locationResponse: Result<
+            LocationWithDeviationInternal,
+            LocationErrorInternal
+          >
+        ) => {
+          return this.deserializeLocationWithDeviationResponse(
+            locationResponse
+          );
+        }
+      );
+    } else {
+      throw new Error('Invalid arguments');
     }
   }
 
   /**
    * Returns a string that is used to uniquely identify the device
+   *
+   * @returns {string} Device ID
    */
-  getDeviceId(): Promise<string> {
+  static async getDeviceId(): Promise<string> {
     return HyperTrackSdk.getDeviceId().then(
       (deviceId: DeviceId) => deviceId.value
     );
   }
 
   /**
-   * Reflects availability of the device for the Nearby search
+   * Returns a list of errors that blocks SDK from tracking
    *
-   * @returns true when is available or false when unavailable
+   * @returns {HyperTrackError[]} List of errors
    */
-  isAvailable(): Promise<boolean> {
-    return HyperTrackSdk.isAvailable().then(
-      (isAvailable: IsAvailable) => isAvailable.value
+  static async getErrors(): Promise<HyperTrackError[]> {
+    return HyperTrackSdk.getErrors().then(
+      (errors: HyperTrackErrorInternal[]) => {
+        return this.deserializeHyperTrackErrors(errors);
+      }
     );
   }
 
   /**
-   * Sets the availability of the device for the Nearby search
+   * Reflects availability of the device for the Nearby search
    *
-   * @param availability true when is available or false when unavailable
+   * @returns true when is available or false when unavailable
    */
-  setAvailability(isAvailable: boolean) {
-    HyperTrackSdk.setAvailability({
-      type: 'isAvailable',
-      value: isAvailable,
-    } as IsAvailable);
+  static async getIsAvailable(): Promise<boolean> {
+    return HyperTrackSdk.getIsAvailable().then(
+      (isAvailable: IsAvailable) => isAvailable.value
+    );
   }
 
   /**
    * Reflects the tracking intent for the device
    *
-   * @return {boolean} Whether the user's movement data is getting tracked or not.
+   * @returns {boolean} Whether the user's movement data is getting tracked or not.
    */
-  isTracking(): Promise<boolean> {
-    return HyperTrackSdk.isTracking().then(
+  static async getIsTracking(): Promise<boolean> {
+    return HyperTrackSdk.getIsTracking().then(
       (isTracking: IsTracking) => isTracking.value
     );
   }
 
   /**
-   * Syncs the device state with the HyperTrack servers
+   * Reflects the current location of the user or an outage reason
    */
-  sync() {
-    HyperTrackSdk.sync();
+  static async getLocation(): Promise<Result<Location, LocationError>> {
+    return HyperTrackSdk.getLocation().then(
+      (locationResponse: Result<LocationInternal, LocationErrorInternal>) => {
+        return this.deserializeLocationResponse(locationResponse);
+      }
+    );
   }
 
   /**
-   * Expresses an intent to start location tracking for the device
+   * Gets the metadata that is set for the device
+   *
+   * @returns {Object} Metadata JSON
    */
-  startTracking() {
-    HyperTrackSdk.startTracking();
+  static async getMetadata(): Promise<Object> {
+    return HyperTrackSdk.getMetadata().then((metadata: Metadata) => {
+      return this.deserializeMetadata(metadata);
+    });
   }
 
   /**
-   * Stops location tracking immediately
+   * Gets the name that is set for the device
+   *
+   * @returns {string} Device name
    */
-  stopTracking() {
-    HyperTrackSdk.stopTracking();
+  static async getName(): Promise<string> {
+    return HyperTrackSdk.getName().then((name: Name) => {
+      return this.deserializeName(name);
+    });
   }
 
   /**
-   * Reflects the current location of the user or an outage reason
+   * Requests one-time location update and returns the location once it is available, or error.
+   *
+   * Only one locate subscription can be active at a time. If you re-subscribe, the old EmitterSubscription
+   * will be automaticaly removed.
+   *
+   * This method will start location tracking if called, and will stop it when the location is received or
+   * the subscription is cancelled. If any other tracking intent is present (e.g. isAvailable is set to `true`),
+   * the tracking will not be stopped.
+   *
+   * @param callback
+   * @returns EmitterSubscription
+   * @example ```js
+   * const subscription = HyperTrack.locate(location => {
+   *  ...
+   * })
+   *
+   * // to unsubscribe
+   * subscription.remove()
+   * ```
    */
-  getLocation(): Promise<Result<Location, LocationError>> {
-    return HyperTrackSdk.getLocation().then(
-      (locationResponse: Result<LocationInternal, LocationErrorInternal>) => {
-        return this.deserializeLocationResponse(locationResponse);
+  static locate(
+    callback: (location: Result<Location, HyperTrackError[]>) => void
+  ) {
+    this.locateSubscription?.remove();
+    this.locateSubscription = EventEmitter.addListener(
+      EVENT_LOCATE,
+      (location: Result<LocationInternal, HyperTrackErrorInternal[]>) => {
+        callback(this.deserializeLocateResponse(location));
       }
     );
+    HyperTrackSdk.locate();
+    return this.locateSubscription;
   }
 
   /**
-   * Sets the name for the device
-   * @param {string} name
+   * Sets the availability of the device for the Nearby search
+   *
+   * @param availability true when is available or false when unavailable
    */
-  setName(name: string) {
-    HyperTrackSdk.setName({
-      type: 'deviceName',
-      value: name,
-    } as DeviceName);
+  static async setIsAvailable(isAvailable: boolean) {
+    HyperTrackSdk.setIsAvailable({
+      type: 'isAvailable',
+      value: isAvailable,
+    } as IsAvailable);
   }
 
   /**
-   * Sets the metadata for the device
-   * @param {Object} data - Metadata JSON
+   * Sets the tracking intent for the device
+   *
+   * @param {boolean} isTracking
    */
-  setMetadata(data: Object) {
-    HyperTrackSdk.setMetadata(data);
+  static async setIsTracking(isTracking: boolean): Promise<void> {
+    HyperTrackSdk.setIsTracking({
+      type: 'isTracking',
+      value: isTracking,
+    } as IsTracking);
   }
 
   /**
-   * Adds a new geotag
+   * Sets the metadata for the device
    *
-   * @param {Object} data - Geotad data JSON
-   * @returns current location if success or LocationError if failure
+   * @param {Object} data - Metadata JSON
    */
-  async addGeotag(data: Object): Promise<Result<Location, LocationError>>;
+  static async setMetadata(data: Object) {
+    HyperTrackSdk.setMetadata({
+      type: 'metadata',
+      value: data,
+    });
+  }
 
   /**
-   * Adds a new geotag with expected location
+   * Sets the name for the device
    *
-   * @param {Object} data - Geotad data JSON
-   * @param {Location} expectedLocation - Expected location
-   * @returns location with deviation if success or LocationError if failure
+   * @param {string} name
    */
-  async addGeotag(
-    data: Object,
-    expectedLocation: Location
-  ): Promise<Result<LocationWithDeviation, LocationError>>;
-
-  async addGeotag(
-    ...args: any[]
-  ): Promise<Result<Location | LocationWithDeviation, LocationError>> {
-    if (args.length === 1 && typeof args[0] === 'object') {
-      return HyperTrackSdk.addGeotag({
-        data: args[0],
-        expectedLocation: undefined,
-      } as GeotagData).then(
-        (locationResponse: Result<LocationInternal, LocationErrorInternal>) => {
-          return this.deserializeLocationResponse(locationResponse);
-        }
-      );
-    } else if (
-      args.length === 2 &&
-      typeof args[0] === 'object' &&
-      this.isLocation(args[1])
-    ) {
-      let expectedLocation = args[1] as Location;
-      return HyperTrackSdk.addGeotag({
-        data: args[0],
-        expectedLocation: {
-          type: 'location',
-          value: {
-            latitude: expectedLocation.latitude,
-            longitude: expectedLocation.longitude,
-          },
-        } as LocationInternal,
-      } as GeotagData).then(
-        (
-          locationResponse: Result<
-            LocationWithDeviationInternal,
-            LocationErrorInternal
-          >
-        ) => {
-          return this.deserializeLocationWithDeviationResponse(
-            locationResponse
-          );
-        }
-      );
-    } else {
-      throw new Error('Invalid arguments');
-    }
+  static async setName(name: string) {
+    HyperTrackSdk.setName({
+      type: 'name',
+      value: name,
+    } as Name);
   }
 
   /**
@@ -245,15 +293,45 @@ export default class HyperTrack {
    * subscription.remove()
    * ```
    */
-  subscribeToErrors(listener: (errors: HyperTrackError[]) => void) {
+  static subscribeToErrors(
+    listener: (errors: HyperTrackError[]) => void
+  ): EmitterSubscription {
     return EventEmitter.addListener(
-      EVENT_ERROR,
+      EVENT_ERRORS,
       (rawErrors: HyperTrackErrorInternal[]) => {
         listener(this.deserializeHyperTrackErrors(rawErrors));
       }
     );
   }
 
+  /**
+   * Subscribe to availability changes
+   *
+   * @param listener
+   * @returns EmitterSubscription
+   * @example
+   * ```js
+   * const subscription = HyperTrack.subscribeToIsAvailable(isAvailable => {
+   *   if (isAvailable) {
+   *     // ... ready to go
+   *   }
+   * })
+   *
+   * // later, to stop listening
+   * subscription.remove()
+   * ```
+   */
+  static subscribeToIsAvailable(
+    listener: (isAvailable: boolean) => void
+  ): EmitterSubscription {
+    return EventEmitter.addListener(
+      EVENT_IS_AVAILABLE,
+      (isAvailable: IsAvailable) => {
+        listener(isAvailable.value);
+      }
+    );
+  }
+
   /**
    * Subscribe to tracking intent changes
    *
@@ -261,7 +339,7 @@ export default class HyperTrack {
    * @returns EmitterSubscription
    * @example
    * ```js
-   * const subscription = HyperTrack.subscribeToTracking(isTracking => {
+   * const subscription = HyperTrack.subscribeToIsTracking(isTracking => {
    *   if (isTracking) {
    *     // ... ready to go
    *   }
@@ -271,9 +349,11 @@ export default class HyperTrack {
    * subscription.remove()
    * ```
    */
-  subscribeToTracking(listener: (isTracking: boolean) => void) {
+  static subscribeToIsTracking(
+    listener: (isTracking: boolean) => void
+  ): EmitterSubscription {
     return EventEmitter.addListener(
-      EVENT_TRACKING,
+      EVENT_IS_TRACKING,
       (isTracking: IsTracking) => {
         listener(isTracking.value);
       }
@@ -281,43 +361,83 @@ export default class HyperTrack {
   }
 
   /**
-   * Subscribe to availability changes
+   * Subscribe to location changes
    *
    * @param listener
    * @returns EmitterSubscription
    * @example
    * ```js
-   * const subscription = HyperTrack.subscribeToAvailability(isAvailable => {
-   *   if (isAvailable) {
-   *     // ... ready to go
-   *   }
+   * const subscription = HyperTrack.subscribeToLocation(location => {
+   *   ...
    * })
    *
    * // later, to stop listening
    * subscription.remove()
    * ```
    */
-  subscribeToAvailability(listener: (isAvailable: boolean) => void) {
+  static subscribeToLocation(
+    listener: (location: Result<Location, LocationError>) => void
+  ) {
     return EventEmitter.addListener(
-      EVENT_AVAILABILITY,
-      (isAvailable: IsAvailable) => {
-        listener(isAvailable.value);
+      EVENT_LOCATION,
+      (location: Result<LocationInternal, LocationErrorInternal>) => {
+        listener(this.deserializeLocationResponse(location));
       }
     );
   }
 
   /** @ignore */
-  private deserializeHyperTrackErrors(
+  private static deserializeHyperTrackErrors(
     errors: HyperTrackErrorInternal[]
   ): HyperTrackError[] {
-    return errors.map(
-      (error: HyperTrackErrorInternal) =>
-        HyperTrackError[error.value as keyof typeof HyperTrackError]
-    );
+    let res = errors.map((error: HyperTrackErrorInternal) => {
+      if (error.type != 'error') {
+        throw new Error('Invalid error type');
+      }
+      return Object.keys(HyperTrackError).find(
+        (key) =>
+          HyperTrackError[key as keyof typeof HyperTrackError] === error.value
+      ) as HyperTrackError;
+    });
+    return res;
   }
 
   /** @ignore */
-  private deserializeLocationResponse(
+  private static deserializeLocateResponse(
+    response: Result<LocationInternal, HyperTrackErrorInternal[]>
+  ): Result<Location, HyperTrackError[]> {
+    switch (response.type) {
+      case 'success':
+        return {
+          type: 'success',
+          value: response.value.value,
+        };
+      case 'failure':
+        return {
+          type: 'failure',
+          value: this.deserializeHyperTrackErrors(response.value),
+        };
+    }
+  }
+
+  /** @ignore */
+  private static deserializeLocationError(
+    locationError: LocationErrorInternal
+  ): LocationError {
+    switch (locationError.type) {
+      case 'notRunning':
+      case 'starting':
+        return locationError;
+      case 'errors':
+        return {
+          type: 'errors',
+          value: this.deserializeHyperTrackErrors(locationError.value),
+        };
+    }
+  }
+
+  /** @ignore */
+  private static deserializeLocationResponse(
     response: Result<LocationInternal, LocationErrorInternal>
   ): Result<Location, LocationError> {
     switch (response.type) {
@@ -335,7 +455,7 @@ export default class HyperTrack {
   }
 
   /** @ignore */
-  private deserializeLocationWithDeviationResponse(
+  private static deserializeLocationWithDeviationResponse(
     response: Result<LocationWithDeviationInternal, LocationErrorInternal>
   ): Result<LocationWithDeviation, LocationError> {
     switch (response.type) {
@@ -361,23 +481,23 @@ export default class HyperTrack {
   }
 
   /** @ignore */
-  private deserializeLocationError(
-    locationError: LocationErrorInternal
-  ): LocationError {
-    switch (locationError.type) {
-      case 'notRunning':
-      case 'starting':
-        return locationError;
-      case 'errors':
-        return {
-          type: 'errors',
-          value: this.deserializeHyperTrackErrors(locationError.value),
-        };
+  private static deserializeMetadata(metadata: Metadata): Object {
+    if (metadata.type != 'metadata') {
+      throw new Error(`Invalid metadata: ${JSON.stringify(metadata)}`);
+    }
+    return metadata.value;
+  }
+
+  /** @ignore */
+  private static deserializeName(name: Name): string {
+    if (name.type != 'name') {
+      throw new Error(`Invalid name: ${JSON.stringify(name)}`);
     }
+    return name.value;
   }
 
   /** @ignore */
-  private isLocation(obj: Location): obj is Location {
+  private static isLocation(obj: Location): obj is Location {
     return (
       'latitude' in obj &&
       typeof obj.latitude == 'number' &&