hypertrack-sdk-react-native 8.2.2 → 9.1.0

package/src/HyperTrack/HyperTrack.ts

@@ -1,4 +1,19 @@
 import { NativeModules, Platform, NativeEventEmitter } 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 { LocationResponse } from './data_types/internal/LocationResponse';
+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 { Geotag } from './data_types/internal/Geotag';
+import type { DeviceName } from './data_types/internal/DeviceName';
+import type { HyperTrackErrorInternal } from './data_types/internal/HyperTrackErrorInternal';
+
+const EVENT_TRACKING = 'onTrackingChanged';
+const EVENT_AVAILABILITY = 'onAvailabilityChanged';
+const EVENT_ERROR = 'onError';
 
 const LINKING_ERROR =
   `The package 'hypertrack-sdk-react-native' doesn't seem to be linked. Make sure: \n\n` +
@@ -6,123 +21,43 @@ const LINKING_ERROR =
   '- You rebuilt the app after installing the package\n' +
   '- You are not using Expo managed workflow\n';
 
-const HyperTrackSdk = NativeModules.HyperTrack
-  ? NativeModules.HyperTrack
+const HyperTrackSdk = NativeModules.HyperTrackReactNativePlugin
+  ? NativeModules.HyperTrackReactNativePlugin
   : new Proxy(
-      {},
-      {
-        get() {
-          throw new Error(LINKING_ERROR);
-        },
-      }
-    );
+    {},
+    {
+      get() {
+        throw new Error(LINKING_ERROR);
+      },
+    }
+  );
 
 const EventEmitter = new NativeEventEmitter(HyperTrackSdk);
 
-export enum SDKError {
-  /**
-   * An error that we couldn't recognize.
-   */
-  GENERAL = 0,
-  /**
-   * Publishable key is invalid. Check your key on hypertrack dashboard setup.
-   */
-  INVALID_PUBLISHABLE_KEY = 1,
-  /**
-   * Your free trial ended or account was not renewed. Check your account on hypertrack dashboard.
-   */
-  AUTHORIZATION_FAILED = 2,
-  /**
-   * Tracking won't start due to denied (or absent) permission.
-   */
-  PERMISSION_DENIED = 3,
-}
-
-/**
- * A base interface for errors in SDK.
- */
-export type Error = {
-  code: SDKError;
-  message?: string;
-};
-
-/**
- * Interface for accessing adding geotag result.
- */
-export enum GeotagError {
-  /** Expected location is not supported on this platform */
-  PLATFORM_NOT_SUPPORTED = 0,
-  /** Expected vs actual location difference is greater then required */
-  LOCATION_MISMATCH = 1,
-  /** SDK can't get actual location from OS sensors */
-  LOCATION_NOT_AVAILABLE = 2,
-  /** Invalid arguments  */
-  INVALID_ARGUMENTS = 3,
-}
-
-export interface Location {
-  location: {
-    latitude: number;
-    longitude: number;
-  };
-}
-
-export enum LocationError {
-  // The user has not chosen whether the app can use location services.
-  // SDK automatically asked for permissions.
-  LOCATION_PERMISSIONS_NOT_DETERMINED = 'location_permissions_not_determined',
-  // The user has not chosen whether the app can use location services.
-  // SDK can't ask for permissions in background.
-  LOCATION_PERMISSIONS_CANT_BE_ASKED_IN_BACKGROUND = 'location_permissions_cant_be_asked_in_background',
-  // Can't start tracking in background with When In Use location
-  // permissions. SDK will automatically start tracking when app will return
-  // to foreground.
-  LOCATION_PERMISSIONS_INSUFFICIENT_FOR_BACKGROUND = 'location_permissions_insufficient_for_background',
-  // The app is not authorized to use location services.
-  LOCATION_PERMISSIONS_RESTRICTED = 'location_permissions_restricted',
-  // The user didn't grant precise location permissions or downgraded permissions to imprecise.
-  LOCATION_PERMISSIONS_REDUCED_ACCURACY = 'location_permissions_reduced_accuracy',
-  // The user denied location permissions.
-  LOCATION_PERMISSIONS_DENIED = 'location_permissions_denied',
-  // The user disabled location services systemwide.
-  LOCATION_SERVICES_DISABLED = 'location_services_disabled',
-  // The user has not chosen whether the app can use motion activity
-  // services. SDK automatically asked for permissions.
-  MOTION_ACTIVITY_PERMISSIONS_NOT_DETERMINED = 'motion_activity_permissions_not_determined',
-  // The user has not chosen whether the app can use motion activity
-  // services. SDK can't ask for permissions in background.
-  MOTION_ACTIVITY_PERMISSIONS_CANT_BE_ASKED_IN_BACKGROUND = 'motion_activity_permissions_cant_be_asked_in_background',
-  // Motion activity permissions denied after SDK's initialization. Granting
-  // them will restart the app, so in effect, they are denied during this app's
-  // session.
-  MOTION_ACTIVITY_PERMISSIONS_DENIED = 'motion_activity_permissions_denied',
-  // The user disabled motion services systemwide.
-  MOTION_ACTIVITY_SERVICES_DISABLED = 'motion_activity_services_disabled',
-  // The SDK is not collecting locations because it's either not tracking or is unavailable.
-  NOT_RUNNING = 'not_running',
-  // GPS satellites are not in view.
-  GPS_SIGNAL_LOST = 'gps_signal_lost',
-  // The SDK started collecting locations and is waiting for OS location services to respond.
-  STARTING = 'starting',
-  // The user enabled mock location app while mocking locations is prohibited.
-  LOCATION_MOCKED = 'location_mocked',
-}
-
 export default class HyperTrack {
-  constructor() {
+  private constructor() {
     return this;
   }
 
-  static async createInstance(
+  /**
+   * Creates an SDK instance
+   * 
+   * @param publishableKey publishable key provided in HyperTrack’s dashboard setup page
+   * @param sdkInitParams
+   * @returns HyperTrack instance
+   */
+  static async initialize(
     publishableKey: string,
-    automaticallyRequestPermissions = true
-  ) {
+    sdkInitParams: SdkInitParams = {}
+  ): Promise<HyperTrack> {
     try {
-      await HyperTrackSdk.initialize(
+      await HyperTrackSdk.initializeSdk({
         publishableKey,
-        false,
-        automaticallyRequestPermissions
-      );
+        loggingEnabled: sdkInitParams.loggingEnabled ?? false,
+        allowMockLocations: sdkInitParams.allowMockLocations ?? false,
+        requireBackgroundTrackingPermission: sdkInitParams.requireBackgroundTrackingPermission ?? false,
+        automaticallyRequestPermissions: sdkInitParams.automaticallyRequestPermissions ?? true,
+      });
       return new HyperTrack();
     } catch (error: any) {
       throw new Error(error.message);
@@ -130,76 +65,118 @@ export default class HyperTrack {
   }
 
   /**
-   * Enables debug log output. This is very verbose, so you shouldn't use this for
-   * production build.
-   */
-  static enableDebugLogging(enable: boolean) {
-    HyperTrackSdk.enableDebugLogging(enable);
-  }
-
-  /**
-   * Returns a string which is used by HyperTrack to uniquely identify the user.
+   * Returns a string that is used to uniquely identify the device
    */
-  async getDeviceID(): Promise<string> {
-    return HyperTrackSdk.getDeviceID();
+  getDeviceId(): Promise<string> {
+    return HyperTrackSdk.getDeviceId().then(
+      (deviceId: DeviceId) => deviceId.value
+    );
   }
 
   /**
-   * Device's availability for nearby search
+   * Reflects availability of the device for the Nearby search
    *
    * @returns true when is available or false when unavailable
    */
   isAvailable(): Promise<boolean> {
-    return HyperTrackSdk.isAvailable();
+    return HyperTrackSdk.isAvailable().then(
+      (isAvailable: IsAvailable) => isAvailable.value
+    );
   }
 
   /**
-   * Allows you to set device availability for nearby search
+   * Sets the availability of the device for the Nearby search
    *
    * @param availability true when is available or false when unavailable
    */
-  async setAvailability(availability: Boolean): Promise<void> {
-    return HyperTrackSdk.setAvailability(availability);
+  setAvailability(isAvailable: boolean) {
+    HyperTrackSdk.setAvailability({
+      type: 'isAvailable',
+      value: isAvailable
+    } as IsAvailable);
   }
 
   /**
-   * Determine whether the SDK is tracking the movement of the user.
+   * Reflects the tracking intent for the device
+   * 
    * @return {boolean} Whether the user's movement data is getting tracked or not.
    */
   isTracking(): Promise<boolean> {
-    return HyperTrackSdk.isTracking();
+    return HyperTrackSdk.isTracking().then(
+      (isTracking: IsTracking) => isTracking.value
+    );
   }
 
   /**
-   * Update device state from server.
+   * Syncs the device state with the HyperTrack servers
    */
-  syncDeviceSettings() {
-    HyperTrackSdk.syncDeviceSettings();
+  sync() {
+    HyperTrackSdk.sync();
   }
 
   /**
-   * Start or resume tracking location and activity events.
+   * Expresses an intent to start location tracking for the device
    */
   startTracking() {
     HyperTrackSdk.startTracking();
   }
 
   /**
-   * Stops the SDK from listening to the user's movement updates and recording any data.
+   * Stops location tracking immediately
    */
   stopTracking() {
     HyperTrackSdk.stopTracking();
   }
 
-  /// The current location of the user or an outage reason.
+  /**
+   * Reflects the current location of the user or an outage reason
+   */
   getLocation(): Promise<LocationError | Location> {
-    return HyperTrackSdk.getLocation();
+    return HyperTrackSdk.getLocation().then(
+      (locationResponse: LocationResponse) => {
+        return this.deserializeLocationResponse(locationResponse);
+      }
+    );
   }
 
   /**
-   * Listen for errors.
+   * Sets the name for the device
+   * @param {string} name
+   */
+  setName(name: string) {
+    HyperTrackSdk.setName({
+      type: 'deviceName',
+      value: name
+    } as DeviceName)
+  }
+
+  /**
+   * Sets the metadata for the device
+   * @param {Object} data - Metadata JSON
+   */
+  setMetadata(data: Object) {
+    HyperTrackSdk.setMetadata(data);
+  }
+
+  /**
+   * Adds a new geotag
+   * @param {Object} data - Geotad data JSON
+   * @returns current location if success or LocationError if failure
+   */
+  addGeotag(data: Object): Promise<LocationError | Location> {
+    return HyperTrackSdk.addGeotag({
+      data
+    } as Geotag).then(
+      (locationResponse: LocationResponse) => {
+        return this.deserializeLocationResponse(locationResponse);
+      }
+    );
+  }
+
+  /**
+   * Subscribe to tracking errors
    *
-   * @param listener (errors: {code, message}) => void
+   * @param listener
    * @returns EmitterSubscription
    * @example
    * ```js
@@ -213,14 +190,16 @@ export default class HyperTrack {
    * subscription.remove()
    * ```
    */
-  subscribeToErrors(listener: (errors: Error) => void) {
-    return EventEmitter.addListener('onTrackingErrorHyperTrack', listener);
+  subscribeToErrors(listener: (errors: HyperTrackError[]) => void) {
+    return EventEmitter.addListener(EVENT_ERROR, (rawErrors: HyperTrackErrorInternal[]) => {
+      listener(this.deserializeHyperTrackErrors(rawErrors))
+    });
   }
 
   /**
-   * Listen for tracking changes.
+   * Subscribe to tracking intent changes
    *
-   * @param listener (isTracking: boolean) => void
+   * @param listener
    * @returns EmitterSubscription
    * @example
    * ```js
@@ -235,39 +214,61 @@ export default class HyperTrack {
    * ```
    */
   subscribeToTracking(listener: (isTracking: boolean) => void) {
-    return EventEmitter.addListener('onTrackingStateChanged', listener);
-  }
-
-  /**
-   * Send device name to HyperTrack
-   * @param {string} name - Device name you want to see in the Dashboard.
-   */
-  setDeviceName(name: string) {
-    HyperTrackSdk.setDeviceName(name);
+    return EventEmitter.addListener(
+      EVENT_TRACKING,
+      (isTracking: IsTracking) => {
+        listener(isTracking.value);
+      }
+    );
   }
 
   /**
-   * Send metadata details to HyperTrack
-   * @param {Object} data - Send extra device information.
+   * Subscribe to availability changes
+   *
+   * @param listener
+   * @returns EmitterSubscription
+   * @example
+   * ```js
+   * const subscription = HyperTrack.subscribeToAvailability(isAvailable => {
+   *   if (isAvailable) {
+   *     // ... ready to go
+   *   }
+   * })
+   *
+   * // later, to stop listening
+   * subscription.remove()
+   * ```
    */
-  setMetadata(data: Object) {
-    HyperTrackSdk.setMetadata(data);
+  subscribeToAvailability(listener: (isAvailable: boolean) => void) {
+    return EventEmitter.addListener(
+      EVENT_AVAILABILITY,
+      (isAvailable: IsAvailable) => {
+        listener(isAvailable.value);
+      }
+    );
   }
 
-  /**
-   * @deprecated
-   * Set a trip marker
-   * @param {Object} _data - Include anything that can be parsed into JSON.
-   */
-  setTripMarker(_data: Object) {
-    throw new Error('Deprecated');
+  /** @ignore */
+  private deserializeHyperTrackErrors(errors: HyperTrackErrorInternal[]): HyperTrackError[] {
+    return errors.map((error: HyperTrackErrorInternal) => HyperTrackError[error.value as keyof typeof HyperTrackError])
   }
 
-  /**
-   * Add geotag
-   * @param {Object} data - Include anything that can be parsed into JSON.
-   */
-  addGeotag(data: Object): Promise<LocationError | Location> {
-    return HyperTrackSdk.addGeotag(data);
+  /** @ignore */
+  private deserializeLocationResponse(response: LocationResponse): Location | LocationError {
+    switch(response.type) {
+      case "success":
+        return response.value
+      case "failure":
+        switch(response.value.type) {
+          case "notRunning":
+          case "starting":
+            return response.value
+          case "errors":
+            return {
+              type: "errors",
+              value: this.deserializeHyperTrackErrors(response.value.value)
+            }
+        }
+    };
   }
 }

package/src/HyperTrack/data_types/HyperTrackError.ts

@@ -0,0 +1,22 @@
+// enum naming convention is ignored to make datatype sync
+// across platforms easier
+export enum HyperTrackError {
+  gpsSignalLost = "gpsSignalLost",
+  locationMocked = "locationMocked",
+  locationPermissionsDenied = "locationPermissionsDenied",
+  locationPermissionsInsufficientForBackground = "locationPermissionsInsufficientForBackground",
+  locationPermissionsNotDetermined = "locationPermissionsNotDetermined",
+  locationPermissionsReducedAccuracy = "locationPermissionsReducedAccuracy",
+  locationPermissionsProvisional = "locationPermissionsProvisional",
+  locationPermissionsRestricted = "locationPermissionsRestricted",
+  locationServicesDisabled = "locationServicesDisabled",
+  locationServicesUnavailable = "locationServicesUnavailable",
+  motionActivityPermissionsNotDetermined = "motionActivityPermissionsNotDetermined",
+  motionActivityPermissionsDenied = "motionActivityPermissionsDenied",
+  motionActivityServicesDisabled = "motionActivityServicesDisabled",
+  motionActivityServicesUnavailable = "motionActivityServicesUnavailable",
+  motionActivityPermissionsRestricted = "motionActivityPermissionsRestricted",
+  networkConnectionUnavailable = "networkConnectionUnavailable",
+  invalidPublishableKey = "invalidPublishableKey",
+  blockedFromRunning = "blockedFromRunning"
+}

package/src/HyperTrack/data_types/Location.ts

@@ -0,0 +1,7 @@
+export type Location = {
+  type: 'location';
+  value: {
+    latitude: number;
+    longitude: number;
+  };
+};

package/src/HyperTrack/data_types/LocationError.ts

@@ -0,0 +1,11 @@
+import type { HyperTrackError } from './HyperTrackError';
+import type { NotRunning, Starting } from './internal/LocationErrorInternal';
+
+export { NotRunning, Starting }
+
+export type Errors = {
+  type: 'errors';
+  value: HyperTrackError[];
+};
+
+export type LocationError = NotRunning | Starting | Errors;

package/src/HyperTrack/data_types/SdkInitParams.ts

@@ -0,0 +1,28 @@
+/**
+ * Parameters for initializing the SDK.
+ */
+export type SdkInitParams = {
+  /**
+   * Enable debug logging.
+   * @default false
+   */
+  loggingEnabled?: boolean;
+
+  /**
+   * Allow mock locations to pass through and don’t send mock location outage.
+   * @default false
+   */
+  allowMockLocations?: boolean;
+
+  /**
+   * Require Background location permissions while requiring permissions on Android.
+   * @default false
+   */
+  requireBackgroundTrackingPermission?: boolean;
+
+  /**
+   * Automatically request permissions on starting tracking on iOS.
+   * @default true
+   */
+  automaticallyRequestPermissions?: boolean;
+};

package/src/HyperTrack/data_types/internal/DeviceId.ts

@@ -0,0 +1,4 @@
+export type DeviceId = {
+  type: 'deviceID';
+  value: string;
+};

package/src/HyperTrack/data_types/internal/DeviceName.ts

@@ -0,0 +1,4 @@
+export type DeviceName = {
+  type: 'deviceName';
+  value: string;
+};

package/src/HyperTrack/data_types/internal/Geotag.ts

@@ -0,0 +1,3 @@
+export type Geotag = {
+    data: Object
+}

package/src/HyperTrack/data_types/internal/HyperTrackErrorInternal.ts

@@ -0,0 +1,4 @@
+export type HyperTrackErrorInternal = {
+    type: "hyperTrackError",
+    value: string
+}

package/src/HyperTrack/data_types/internal/IsAvailable.ts

@@ -0,0 +1,4 @@
+export type IsAvailable = {
+  type: 'isAvailable';
+  value: boolean;
+};

package/src/HyperTrack/data_types/internal/IsTracking.ts

@@ -0,0 +1,4 @@
+export type IsTracking = {
+  type: 'isTracking';
+  value: boolean;
+};

package/src/HyperTrack/data_types/internal/LocationErrorInternal.ts

@@ -0,0 +1,14 @@
+import type { HyperTrackErrorInternal } from './HyperTrackErrorInternal';
+
+export type NotRunning = {
+  type: 'notRunning';
+};
+export type Starting = {
+  type: 'starting';
+};
+export type ErrorsInternal = {
+  type: 'errors';
+  value: HyperTrackErrorInternal[];
+};
+
+export type LocationErrorInternal = NotRunning | Starting | ErrorsInternal;

package/src/HyperTrack/data_types/internal/LocationResponse.ts

@@ -0,0 +1,14 @@
+import type { Location } from '../Location';
+import type { LocationErrorInternal } from './LocationErrorInternal';
+
+export type LocationSuccess = {
+  type: 'success';
+  value: Location;
+};
+
+export type LocationFailure = {
+  type: 'failure';
+  value: LocationErrorInternal;
+};
+
+export type LocationResponse = LocationSuccess | LocationFailure;

package/src/index.tsx

@@ -2,10 +2,7 @@ import HyperTrack from './HyperTrack/HyperTrack';
 export default HyperTrack;
 export { HyperTrack };
 
-export {
-  Location,
-  Error,
-  SDKError,
-  GeotagError,
-  LocationError,
-} from './HyperTrack/HyperTrack';
+export { HyperTrackError } from './HyperTrack/data_types/HyperTrackError';
+export { LocationError, NotRunning, Starting, Errors } from './HyperTrack/data_types/LocationError';
+export { Location } from './HyperTrack/data_types/Location';
+export { SdkInitParams } from './HyperTrack/data_types/SdkInitParams'