@josuelmm/cordova-background-geolocation 2.3.5

package/www/BackgroundGeolocation.d.ts

@@ -0,0 +1,910 @@
+// Type definitions for @josuelmm/cordova-background-geolocation.
+// Project: https://github.com/josuelmm/cordova-background-geolocation
+// Definitions by: Mauron85 (@mauron85), Norbert Györög (@djereg)
+// Definitions: https://github.com/josuelmm/cordova-background-geolocation/blob/master/www/BackgroundGeolocation.d.ts
+
+type Event = 'location' | 'stationary' | 'activity' | 'start' | 'stop' | 'error' | 'authorization' | 'foreground' | 'background' | 'abort_requested' | 'http_authorization';
+type HeadlessTaskEventName = 'location' | 'stationary' | 'activity';
+type iOSActivityType = 'AutomotiveNavigation' | 'OtherNavigation' | 'Fitness' | 'Other';
+type NativeProvider = 'gps' | 'network' | 'passive' | 'fused';
+type ActivityType = 'IN_VEHICLE' | 'ON_BICYCLE' | 'ON_FOOT' | 'RUNNING' | 'STILL' | 'TILTING' | 'UNKNOWN' | 'WALKING';
+type LogLevel = 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+type LocationProvider = 0 | 1 | 2;
+type AuthorizationStatus = 0 | 1 | 2;
+type AccuracyLevel = 0 | 100 | 1000 | 10000 | number;
+type LocationErrorCode = 1 | 2 | 3;
+type ServiceMode = 0 | 1;
+
+export interface Unsubscribable {
+  unsubscribe(): void;
+}
+
+export interface Subscribable<T> {
+  subscribe(callback: (value: T) => any): Unsubscribable;
+}
+
+export interface ConfigureOptions {
+  /**
+   * Set location provider
+   *
+   * Platform: all
+   * Available providers:
+   *  DISTANCE_FILTER_PROVIDER,
+   *  ACTIVITY_PROVIDER
+   *  RAW_PROVIDER
+   *
+   * @default DISTANCE_FILTER_PROVIDER
+   * @example
+   * { locationProvider: BackgroundGeolocation.RAW_PROVIDER }
+   */
+  locationProvider?: LocationProvider;
+
+  /**
+   * Desired accuracy in meters.
+   *
+   * Platform: all
+   * Provider: all
+   * Possible values:
+   *  HIGH_ACCURACY,
+   *  MEDIUM_ACCURACY,
+   *  LOW_ACCURACY,
+   *  PASSIVE_ACCURACY
+   * Note: Accuracy has direct effect on power drain. Lower accuracy = lower power drain.
+   *
+   * @default MEDIUM_ACCURACY
+   * @example
+   * { desiredAccuracy: BackgroundGeolocation.LOW_ACCURACY }
+   */
+  desiredAccuracy?: AccuracyLevel;
+
+  /**
+   * Stationary radius in meters.
+   *
+   * When stopped, the minimum distance the device must move beyond the stationary location for aggressive background-tracking to engage.
+   * Platform: all
+   * Provider: DISTANCE_FILTER
+   *
+   * @default 50
+   */
+  stationaryRadius?: number;
+
+  /**
+   * When enabled, the plugin will emit sounds for life-cycle events of background-geolocation! See debugging sounds table.
+   *
+   * Platform: all
+   * Provider: all
+   *
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * The minimum distance (measured in meters) a device must move horizontally before an update event is generated.
+   *
+   * Platform: all
+   * Provider: DISTANCE_FILTER, RAW
+   *
+   * @default 500
+   * @see {@link https://apple.co/2oHo2CV|Apple docs}
+   */
+  distanceFilter?: number;
+
+  /**
+   * Enable this in order to force a stop() when the application terminated.
+   * E.g. on iOS, double-tap home button, swipe away the app.
+   *
+   * Platform: all
+   * Provider: all
+   *
+   * @default true
+   */
+  stopOnTerminate?: boolean;
+
+  /**
+   * Start background service on device boot.
+   *
+   * Platform: Android
+   * Provider: all
+   *
+   * @default false
+   */
+  startOnBoot?: boolean;
+
+  /**
+   * The minimum time interval between location updates in milliseconds.
+   *
+   * Platform: Android
+   * Provider: all
+   *
+   * @default 60000
+   * @see {@link https://bit.ly/1x00RUu|Android docs}
+   */
+  interval?: number;
+
+  /**
+   * Fastest rate in milliseconds at which your app can handle location updates.
+   *
+   * Platform: Android
+   * Provider: ACTIVITY
+   *
+   * @default 120000
+   * @see {@link https://bit.ly/1x00RUu|Android docs}
+   */
+  fastestInterval?: number;
+
+  /**
+   * Rate in milliseconds at which activity recognition occurs.
+   * Larger values will result in fewer activity detections while improving battery life.
+   *
+   * Platform: Android
+   * Provider: ACTIVITY
+   *
+   * @default 10000
+   */
+  activitiesInterval?: number;
+
+  /**
+   * @deprecated Stop location updates, when the STILL activity is detected.
+   */
+  stopOnStillActivity?: boolean;
+
+  /**
+   * Enable/disable local notifications when tracking and syncing locations.
+   *
+   * Platform: Android
+   * Provider: all
+   *
+   * @default true
+   */
+  notificationsEnabled?: boolean;
+
+  /**
+   * Allow location sync service to run in foreground state.
+   * Foreground state also requires a notification to be presented to the user.
+   *
+   * Platform: Android
+   * Provider: all
+   *
+   * @default false
+   */
+  startForeground?: boolean;
+
+  /**
+   * Custom notification title in the drawer.
+   *
+   * Platform: Android
+   * Provider: all
+
+   * @default "Background tracking"
+   */
+  notificationTitle?: string;
+
+  /**
+   * Custom notification text in the drawer.
+   *
+   * Platform: Android
+   * Provider: all
+   *
+   * @default "ENABLED"
+   */
+  notificationText?: string;
+
+  /**
+   * The accent color (hex triplet) to use for notification.
+   * Eg. <code>#4CAF50</code>.
+   *
+   * Platform: Android
+   * Provider: all
+   */
+  notificationIconColor?: string;
+
+  /**
+   * The filename of a custom notification icon.
+   *
+   * Platform: Android
+   * Provider: all
+   */
+  notificationIconLarge?: string;
+
+  /**
+   * The filename of a custom notification icon.
+   *
+   * Platform: Android
+   * Provider: all
+   */
+  notificationIconSmall?: string;
+
+  /**
+   * Activity type.
+   * Presumably, this affects iOS GPS algorithm.
+   *
+   * Possible values:
+   * "AutomotiveNavigation", "OtherNavigation", "Fitness", "Other"
+   *
+   * Platform: iOS
+   * Provider: all
+   *
+   * @default "OtherNavigation"
+   * @see {@link https://apple.co/2oHofpH|Apple docs}
+   */
+  activityType?: iOSActivityType;
+
+  /**
+   * Pauses location updates when app is paused.
+   *
+   * Platform: iOS
+   * Provider: all
+   *
+   * @default false
+   * @see {@link https://apple.co/2CbjEW2|Apple docs}
+   */
+  pauseLocationUpdates?: boolean;
+
+  /**
+   * Switch to less accurate significant changes and region monitory when in background.
+   *
+   * Platform: iOS
+   * Provider: all
+   *
+   * @default false
+   */
+  saveBatteryOnBackground?: boolean;
+
+  /**
+   * Server url where to send HTTP POST with recorded locations
+   *
+   * Platform: all
+   * Provider: all
+   */
+  url?: string;
+
+  /**
+   * Server url where to send fail to post locations
+   *
+   * Platform: all
+   * Provider: all
+   */
+  syncUrl?: string;
+
+  /**
+   * Specifies how many previously failed locations will be sent to server at once.
+   *
+   * Platform: all
+   * Provider: all
+   *
+   * @default 100
+   */
+  syncThreshold?: string;
+
+  /**
+   * Optional HTTP headers sent along in HTTP request.
+   *
+   * Platform: all
+   * Provider: all
+   */
+  httpHeaders?: any;
+
+  /**
+   * Limit maximum number of locations stored into db.
+   *
+   * Platform: all
+   * Provider: all
+   *
+   * @default 10000
+   */
+  maxLocations?: number;
+
+  /**
+   * Customization post template.
+   *
+   * Platform: all
+   * Provider: all
+   */
+  postTemplate?: any;
+}
+
+export interface LocationOptions {
+  /**
+   * Maximum time in milliseconds device will wait for location.
+   */
+  timeout?: number;
+
+  /**
+   * Maximum age in milliseconds of a possible cached location that is acceptable to return.
+   */
+  maximumAge?: number;
+
+  /**
+   * If true and if the device is able to provide a more accurate position, it will do so.
+   */
+  enableHighAccuracy?: boolean;
+}
+
+export interface Location {
+  /** ID of location as stored in DB (or null) */
+  id: number;
+
+  /**
+   * Native provider reponsible for location.
+   *
+   * Possible values:
+   * "gps", "network", "passive" or "fused"
+   */
+  provider: NativeProvider;
+
+  /** Configured location provider. */
+  locationProvider: number;
+
+  /** UTC time of this fix, in milliseconds since January 1, 1970. */
+  time: number;
+
+  /** Latitude, in degrees. */
+  latitude: number;
+
+  /** Longitude, in degrees. */
+  longitude: number;
+
+  /** Estimated accuracy of this location, in meters. */
+  accuracy: number;
+
+  /**
+   * Speed if it is available, in meters/second over ground.
+   *
+   * Note: Not all providers are capable of providing speed.
+   * Typically network providers are not able to do so.
+   */
+  speed: number;
+
+  /** Altitude if available, in meters above the WGS 84 reference ellipsoid. */
+  altitude: number;
+
+  /** Bearing, in degrees. */
+  bearing: number;
+
+  /**
+   * True if location was recorded by mock provider. (ANDROID ONLY)
+   *
+   * Note: this property is not enabled by default!
+   * You can enable it "postTemplate" configure option.
+   */
+  isFromMockProvider?: boolean;
+
+  /**
+   * True if device has mock locations enabled. (ANDROID ONLY)
+   *
+   * Note: this property is not enabled by default!
+   * You can enable it "postTemplate" configure option.
+   */
+  mockLocationsEnabled?: boolean;
+}
+
+export interface StationaryLocation extends Location {
+  radius: number
+}
+
+export interface LocationError {
+  /**
+   * Reason of an error occurring when using the geolocating device.
+   *
+   * Possible error codes:
+   *  1. PERMISSION_DENIED
+   *  2. LOCATION_UNAVAILABLE
+   *  3. TIMEOUT
+   */
+  code: LocationErrorCode;
+
+  /** Message describing the details of the error */
+  message: string;
+}
+
+export interface BackgroundGeolocationError {
+  code: number;
+  message: string;
+}
+
+export interface Activity {
+  /** Percentage indicating the likelihood user is performing this activity. */
+  confidence: number;
+
+  /**
+   * Type of the activity.
+   *
+   * Possible values:
+   * IN_VEHICLE, ON_BICYCLE, ON_FOOT, RUNNING, STILL, TILTING, UNKNOWN, WALKING
+   */
+  type: ActivityType;
+}
+
+export interface ServiceStatus {
+  /** TRUE if service is running. */
+  isRunning: boolean;
+
+  /** TRUE if location services are enabled */
+  locationServicesEnabled: boolean;
+
+  /**
+   * Authorization status.
+   *
+   * Posible values:
+   *  NOT_AUTHORIZED, AUTHORIZED, AUTHORIZED_FOREGROUND
+   *
+   * @example
+   * if (authorization == BackgroundGeolocation.NOT_AUTHORIZED) {...}
+   */
+  authorization: AuthorizationStatus;
+}
+
+export interface LogEntry {
+  /** ID of log entry as stored in db. */
+  id: number;
+
+  /** Timestamp in milliseconds since beginning of UNIX epoch. */
+  timestamp: number;
+
+  /** Log level */
+  level: LogLevel;
+
+  /** Log message */
+  message: string;
+
+  /** Recorded stacktrace. (Android only, on iOS part of message) */
+  stackTrace: string;
+}
+
+export interface EventSubscription {
+  remove(): void;
+}
+
+export interface HeadlessTaskEvent {
+  /** Name of the event [ "location", "stationary", "activity" ] */
+  name: HeadlessTaskEventName;
+
+  /** Event parameters. */
+  params: any;
+}
+
+export interface BackgroundGeolocationPlugin {
+
+  DISTANCE_FILTER_PROVIDER: LocationProvider;
+  ACTIVITY_PROVIDER: LocationProvider;
+  RAW_PROVIDER: LocationProvider;
+
+  BACKGROUND_MODE: ServiceMode;
+  FOREGROUND_MODE: ServiceMode;
+
+  NOT_AUTHORIZED: AuthorizationStatus;
+  AUTHORIZED: AuthorizationStatus;
+  AUTHORIZED_FOREGROUND: AuthorizationStatus;
+
+  HIGH_ACCURACY: AccuracyLevel;
+  MEDIUM_ACCURACY: AccuracyLevel;
+  LOW_ACCURACY: AccuracyLevel;
+  PASSIVE_ACCURACY: AccuracyLevel;
+
+  LOG_ERROR: LogLevel;
+  LOG_WARN: LogLevel;
+  LOG_INFO: LogLevel;
+  LOG_DEBUG: LogLevel;
+  LOG_TRACE: LogLevel;
+
+  PERMISSION_DENIED: LocationErrorCode;
+  LOCATION_UNAVAILABLE: LocationErrorCode;
+  TIMEOUT: LocationErrorCode;
+
+  events: Event[];
+
+  /**
+   * Configure plugin.
+   * Platform: iOS, Android
+   *
+   * @param options
+   * @param success
+   * @param fail
+   */
+  configure(
+    options: ConfigureOptions,
+    success?: () => void,
+    fail?: () => void
+  ): Promise<void>;
+
+  /**
+   * Start background geolocation.
+   * Platform: iOS, Android
+   */
+  start(): Promise<void>;
+
+  /**
+   * Stop background geolocation.
+   * Platform: iOS, Android
+   */
+  stop(): Promise<void>;
+
+  /**
+   * One time location check to get current location of the device.
+   *
+   * Platform: all
+   *
+   * @param success
+   * @param fail
+   * @param options
+   */
+  getCurrentLocation(
+    success?: (location: Location) => void,
+    fail?: (error: LocationError) => void | null,
+    options?: LocationOptions
+  ): Promise<Location>;
+
+  /**
+   * Returns current stationaryLocation if available. Null if not
+   *
+   * Platform: all
+   *
+   * @param success
+   * @param fail
+   */
+  getStationaryLocation(
+    success?: (location: StationaryLocation | null) => void,
+    fail?: (error: BackgroundGeolocationError) => void,
+  ): Promise<StationaryLocation>;
+
+  /**
+   * Check status of the service
+   *
+   * @param success
+   * @param fail
+   */
+  checkStatus(
+    success?: (status: ServiceStatus) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<ServiceStatus>;
+
+  /**
+   * Show app settings to allow change of app location permissions.
+   *
+   * Platform: Android >= 6, iOS >= 8.0
+   */
+  showAppSettings(): Promise<void>;
+
+  /**
+   * Show system settings to allow configuration of current location sources.
+   *
+   * Platform: Android
+   */
+  showLocationSettings(): Promise<void>;
+
+  /**
+   * Return all stored locations.
+   * Useful for initial rendering of user location on a map just after application launch.
+   *
+   * Platform: iOS, Android
+   *
+   * @param success
+   * @param fail
+   */
+  getLocations(
+    success?: (locations: Location[]) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<Location[]>;
+
+  /**
+   * Method will return locations which have not yet been posted to server.
+   * Platform: iOS, Android
+   * @param success
+   * @param fail
+   */
+  getValidLocations(
+    success?: (location: Location[]) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<Location[]>;
+
+    /**
+   * Method will return locations which have not yet been posted to server and delete to avoid getting them again.
+   * Platform: iOS, Android
+   * @param success
+   * @param fail
+   */
+  getValidLocationsAndDelete(
+    success?: (location: Location[]) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<Location[]>;
+
+  /**
+   * Delete location by locationId.
+   *
+   * Platform: iOS, Android
+   *
+   * @param locationId
+   * @param success
+   * @param fail
+   */
+  deleteLocation(
+    locationId: number,
+    success?: () => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<void>;
+
+  /**
+   * Delete all stored locations.
+   *
+   * Platform: iOS, Android
+   *
+   * Note: You don't need to delete all locations.
+   * The plugin manages the number of stored locations automatically and the total count never exceeds the number as defined by <code>option.maxLocations</code>.
+   *
+   * @param success
+   * @param fail
+   */
+  deleteAllLocations(
+    success?: () => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<void>;
+
+  /**
+   * Switch plugin operation mode,
+   *
+   * Platform: iOS
+   *
+   * Normally the plugin will handle switching between <b>BACKGROUND</b> and <b>FOREGROUND</b> mode itself.
+   * Calling <code>switchMode</code> you can override plugin behavior and force it to switch into other mode.
+   *
+   * @example
+   * // switch to FOREGROUND mode
+   * BackgroundGeolocation.switchMode(BackgroundGeolocation.FOREGROUND_MODE);
+   *
+   * // switch to BACKGROUND mode
+   * BackgroundGeolocation.switchMode(BackgroundGeolocation.BACKGROUND_MODE);
+   */
+  switchMode(
+    modeId: ServiceMode,
+    success?: () => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<void>;
+
+  /**
+   * Force sync of pending locations.
+   * Option <code>syncThreshold</code> will be ignored and all pending locations will be immediately posted to <code>syncUrl</code> in single batch.
+   *
+   * Platform: Android, iOS
+   *
+   * @param success
+   * @param fail
+   */
+  forceSync(
+    success?: () => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<void>;
+
+  /**
+   * Get stored configuration options.
+   *
+   * @param success
+   * @param fail
+   */
+  getConfig(
+    success?: (options: ConfigureOptions) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<ConfigureOptions>;
+
+  /**
+   * Return all logged events. Useful for plugin debugging.
+   *
+   * Platform: Android, iOS
+   *
+   * @param limit Limits number of returned entries.
+   * @param fromId Return entries after <code>fromId</code>. Useful if you plan to implement infinite log scrolling
+   * @param minLevel Available levels: ["TRACE", "DEBUG", "INFO", "WARN", "ERROR"]
+   * @param success
+   * @param fail
+   */
+  getLogEntries(
+    limit: number,
+    fromId: number,
+    minLevel: LogLevel,
+    success?: (entries: LogEntry[]) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<LogEntry[]>;
+
+  /**
+   * Unregister all event listeners for given event.
+   *
+   * If parameter <code>event</code> is not provided then all event listeners will be removed.
+   *
+   * @param event
+   */
+  removeAllListeners(event?: Event): void;
+
+
+  /**
+   * Start background task (iOS only)
+   *
+   * To perform any long running operation on iOS
+   * you need to create background task
+   * IMPORTANT: task has to be ended by endTask
+   *
+   * @param success
+   * @param fail
+   */
+  startTask(
+    success?: (taskKey: number) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<number>;
+
+  /**
+   * End background task indentified by taskKey (iOS only)
+   *
+   * @param taskKey
+   * @param success
+   * @param fail
+   */
+  endTask(
+    taskKey: number,
+    success?: () => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<void>;
+
+  /**
+   * A special task that gets executed when the app is terminated, but
+   * the plugin was configured to continue running in the background
+   * (option <code>stopOnTerminate: false</code>).
+   *
+   * In this scenario the Activity was killed by the system and all registered
+   * event listeners will not be triggered until the app is relaunched.
+   *
+   * @example
+   *  BackgroundGeolocation.headlessTask(function(event) {
+   *
+   *      if (event.name === 'location' || event.name === 'stationary') {
+   *          var xhr = new XMLHttpRequest();
+   *          xhr.open('POST', 'http://192.168.81.14:3000/headless');
+   *          xhr.setRequestHeader('Content-Type', 'application/json');
+   *          xhr.send(JSON.stringify(event.params));
+   *      }
+   *
+   *      return 'Processing event: ' + event.name; // will be logged
+   *  });
+   */
+  headlessTask(
+    task: (event: HeadlessTaskEvent) => void
+  ): void;
+
+  /**
+   * Register location event listener.
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'location',
+    callback?: (location: Location) => void
+  ): Subscribable<Location>;
+
+  /**
+   * Register stationary location event listener.
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'stationary',
+    callback?: (location: StationaryLocation) => void
+  ): Subscribable<StationaryLocation>;
+
+  /**
+   * Register activity monitoring listener.
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'activity',
+    callback?: (activity: Activity) => void
+  ): Subscribable<Activity>;
+
+  /**
+   * Register start event listener.
+   *
+   * Event is triggered when background service has been started succesfully.
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'start',
+    callback?: () => void
+  ): Subscribable<void>;
+
+  /**
+   * Register stop event listener.
+   *
+   * Triggered when background service has been stopped succesfully.
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'stop',
+    callback?: () => void
+  ): Subscribable<void>;
+
+  /**
+   * Register error listener.
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'error',
+    callback?: (error: BackgroundGeolocationError) => void
+  ): Subscribable<BackgroundGeolocationError>;
+
+  /**
+   * Register authorization listener.
+   *
+   * Triggered when user changes authorization/permissions for
+   * the app or toggles location services.
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'authorization',
+    callback?: (status: AuthorizationStatus) => void
+  ): Subscribable<AuthorizationStatus>;
+
+  /**
+   * Register foreground event listener.
+   *
+   * Triggered when app entered foreground state and (visible to the user).
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'foreground',
+    callback?: () => void
+  ): Subscribable<void>;
+
+  /**
+   * Register background event listener.
+   *
+   * Triggered when app entered background state and (not visible to the user).
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'background',
+    callback?: () => void
+  ): Subscribable<void>;
+
+  /**
+   * Register abort_requested event listener.
+   *
+   * Triggered when server responded with "<code>285 Updates Not Required</code>" to post/sync request.
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'abort_requested',
+    callback?: () => void
+  ): Subscribable<void>;
+
+  /**
+   * Register http_authorization event listener.
+   *
+   * Triggered when server responded with "<code>401 Unauthorized</code>" to post/sync request.
+   *
+   * @param eventName
+   * @param callback
+   */
+  on(
+    eventName: 'http_authorization',
+    callback?: () => void
+  ): Subscribable<void>;
+
+}
+
+declare const BackgroundGeolocation: BackgroundGeolocationPlugin;
+
+export default BackgroundGeolocation;