@transistorsoft/background-geolocation-types 5.0.0-beta.2 → 5.0.0-beta.4

package/dist/core/api/BackgroundGeolocation.d.ts

@@ -1,374 +1,130 @@
-/**
- * Primary BackgroundGeolocation API
- *
- * __Overview__
- *
- * The `BackgroundGeolocation` interface defines the **complete, strongly-typed API surface**
- * for Transistor Software’s Background Geolocation SDK.
- * This is the main entry-point used by all JavaScript adapters:
- *
- * - React Native (`{{pluginName}}`)
- * - Capacitor
- * - Cordova
- *
- * The API provides:
- *
- * - **Configuration** via a single {@link Config} object composed of modular
- *   sub-configs (`GeoConfig`, `HttpConfig`, `PersistenceConfig`, etc)
- * - **Lifecycle control** (`ready`, `start`, `stop`, `setConfig`, `reset`)
- * - **Location tracking** (motion-based tracking, `getCurrentPosition`,
- *   `watchPosition`)
- * - **Geofencing** (`addGeofence`, `onGeofence`, etc)
- * - **Events subsystem** with fully-typed callbacks (`onLocation`,
- *   `onMotionChange`, `onHttp`, `onProviderChange`, etc)
- * - **Native services** such as background-tasks, authorization workflows,
- *   scheduling, and device-capability checks
- * - **Persistence + HTTP** via an internal SQLite buffer and optional
- *   auto-upload system
- *
- * __Typed Configuration (Compound Config)__
- *
- * Instead of a large “flat” configuration object, the SDK uses a
- * *compound-configuration model*:
- *
- * ```ts
- * import BackgroundGeolocation, {
- *   Config,
- *   GeoConfig,
- *   HttpConfig
- * } from "{{pluginName}}";
- *
- * const config: Config = {
- *   geolocation: {
- *     desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High,
- *     distanceFilter: 20
- *   },
- *   http: {
- *     url: "https://example.com/locations",
- *     autoSync: true
- *   },
- *   persistence: {
- *     maxDaysToPersist: 7
- *   }
- * };
- *
- * BackgroundGeolocation.ready(config);
- * ```
- *
- * This structure ensures:
- *
- * - **Clear separation of concerns**
- * - **Type-safe configuration**
- * - **Automatic backwards-compatibility** with legacy flat keys
- *
- * __Typed Enum Namespaces__
- *
- * All configuration flags that were previously “magic constants”
- * (e.g., `LOG_LEVEL_VERBOSE`, `DESIRED_ACCURACY_HIGH`) now live in
- * strongly-typed namespaces attached to the default export:
- *
- * - {@link BackgroundGeolocation.LogLevel}
- * - {@link BackgroundGeolocation.DesiredAccuracy}
- * - {@link BackgroundGeolocation.PersistMode}
- * - {@link BackgroundGeolocation.NotificationPriority}
- * - {@link BackgroundGeolocation.Event}
- * - …and more
- *
- * These can also be imported individually:
- *
- * ```ts
- * import BackgroundGeolocation, { LogLevel } from "{{pluginName}}";
- *
- * BackgroundGeolocation.ready({
- *   logger: {
- *     logLevel: LogLevel.Debug
- *   }
- * });
- * ```
- *
- * __Event System__
- *
- * The SDK exposes a robust, typed event API:
- *
- * ```ts
- * BackgroundGeolocation.onLocation((location) => {
- *   console.log("New location:", location);
- * });
- *
- * BackgroundGeolocation.onMotionChange((event) => {
- *   console.log("Device is moving?", event.isMoving);
- * });
- * ```
- *
- * All events return **Subscription** objects which must be removed when no longer
- * needed:
- *
- * ```ts
- * const sub = BackgroundGeolocation.onHttp((e) => { ... });
- * sub.remove();
- * ```
- *
- * __Native Lifecycle Requirements__
- *
- * On both iOS and Android, `BackgroundGeolocation.ready(config)` must be called
- * **exactly once per app launch**, before calling `start()`.
- * The SDK automatically restores its last-known configuration from persistent
- * storage after first install.
- *
- * __Philosophy of Operation__
- *
- * Transistorsoft’s tracking engine is built around:
- *
- * - **Motion-based state transitions** (stationary ↔ moving)
- * - **Aggressive tracking only when moving**
- * - **Energy-efficient passive monitoring when stationary**
- * - **Reliable persistence via SQLite**
- * - **Automatic retries + batching** for HTTP uploads
- *
- * Combined, this enables *battery-efficient*, *high-quality* background tracking
- * across iOS and Android.
- *
- * __Capabilities__
- *
- * - High-frequency tracking while the device is moving
- * - Zero-movement battery preservation
- * - Geofence monitoring at scale (thousands of geofences)
- * - Offline storage + sync when network is restored
- * - Background tasks for long-running operations
- * - Authorization state + system diagnostics
- *
- * __Getting Started__
- *
- * ```ts
- * import BackgroundGeolocation from "{{pluginName}}";
- *
- * const state = await BackgroundGeolocation.ready({
- *   geolocation: { distanceFilter: 10 },
- *   http: { url: "https://example.com/locations", autoSync: true }
- * });
- *
- * if (!state.enabled) {
- *   await BackgroundGeolocation.start();
- * }
- * ```
- *
- * Once `start()` is called, the SDK begins operating according to your
- * configuration and continues running—even in the background—until you call
- * `stop()`.
- *
- * @category Primary API
- */
+import type { Logger } from './Logger';
+import type { DeviceSettings } from './DeviceSettings';
+import type { CurrentPositionRequest } from './CurrentPositionRequest';
+import type { Config } from '../config/Config';
+import type { State } from './State';
+import type { Location } from '../data/Location';
+import type { LocationError } from '../../enums/LocationError';
+import type { Geofence } from '../data/Geofence';
+import type { DeviceInfo } from '../data/DeviceInfo';
+import type { Sensors } from '../data/Sensors';
+import type { Subscription } from '../events/Subscription';
+import type { GeofenceEvent } from '../events/GeofenceEvent';
+import type { AuthorizationEvent } from '../events/AuthorizationEvent';
+import type { MotionActivityEvent } from '../events/MotionActivityEvent';
+import type { HeadlessEvent } from '../events/HeadlessEvent';
+import type { HeartbeatEvent } from '../events/HeartbeatEvent';
+import type { GeofencesChangeEvent } from '../events/GeofencesChangeEvent';
+import type { ConnectivityChangeEvent } from '../events/ConnectivityChangeEvent';
+import type { MotionChangeEvent } from '../events/MotionChangeEvent';
+import type { ProviderChangeEvent } from '../events/ProviderChangeEvent';
+import type { HttpEvent } from '../events/HttpEvent';
+import type { AuthorizationStatus } from '../../enums/AuthorizationStatus';
+import type { LogLevel } from '../../enums/LogLevel';
+import type { PersistMode } from '../../enums/PersistMode';
+import type { AccuracyAuthorization } from '../../enums/AccuracyAuthorization';
+export interface EventPayloads {
+    location: Location;
+    motionchange: MotionChangeEvent;
+    activitychange: MotionActivityEvent;
+    geofence: GeofenceEvent;
+    geofenceschange: GeofencesChangeEvent;
+    http: HttpEvent;
+    heartbeat: HeartbeatEvent;
+    providerchange: ProviderChangeEvent;
+    authorization: AuthorizationEvent;
+    connectivitychange: ConnectivityChangeEvent;
+    enabledchange: {
+        enabled: boolean;
+    };
+    powersavechange: {
+        isPowerSaveMode: boolean;
+    };
+    schedule: {
+        identifier?: string;
+    };
+    notification: {
+        action: string;
+    };
+    [event: string]: any;
+}
+export interface BackgroundGeolocationEvents {
+    onLocation(cb: (location: Location) => void, onError?: (err: LocationError) => void): Subscription;
+    onMotionChange(cb: (event: MotionChangeEvent) => void): Subscription;
+    onGeofence(cb: (event: GeofenceEvent) => void): Subscription;
+    onGeofencesChange(cb: (event: GeofencesChangeEvent) => void): Subscription;
+    onActivityChange(cb: (event: MotionActivityEvent) => void): Subscription;
+    onProviderChange(cb: (event: ProviderChangeEvent) => void): Subscription;
+    onHeartbeat(cb: (event: HeartbeatEvent) => void): Subscription;
+    onHttp(cb: (event: HttpEvent) => void): Subscription;
+    onSchedule(cb: (state: State) => void): Subscription;
+    onConnectivityChange(cb: (event: ConnectivityChangeEvent) => void): Subscription;
+    onPowerSaveChange(cb: (enabled: boolean) => void): Subscription;
+    onEnabledChange(cb: (enabled: boolean) => void): Subscription;
+    onNotificationAction(cb: (buttonId: string) => void): Subscription;
+    onAuthorization(cb: (event: AuthorizationEvent) => void): Subscription;
+    addListener(event: string, success: Function, failure?: Function): void;
+    removeListener(event: string, cb: Function): void;
+    removeListeners(): Promise<void>;
+    registerHeadlessTask(callback: (event: HeadlessEvent) => Promise<void>): void;
+}
+export interface BackgroundGeolocationAPI extends BackgroundGeolocationEvents {
+    readonly deviceSettings: DeviceSettings;
+    readonly logger: Logger;
+    ready(config: Config): Promise<State>;
+    reset(config: Config): Promise<State>;
+    start(): Promise<State>;
+    stop(): Promise<State>;
+    changePace(isMoving: boolean): Promise<State>;
+    startGeofences(): Promise<State>;
+    getState(): Promise<State>;
+    setConfig(config: Partial<Config>): Promise<State>;
+    getCurrentPosition(options?: CurrentPositionRequest): Promise<Location>;
+    watchPosition(cb: (location: Location) => void, options?: CurrentPositionRequest): Subscription;
+    stopWatchPosition?(sub?: Subscription): void;
+    resetOdometer(): Promise<number>;
+    setOdometer(value: number): Promise<number>;
+    getOdometer(): Promise<number>;
+    getProviderState(): Promise<ProviderChangeEvent>;
+    requestPermission(): Promise<AuthorizationStatus>;
+    requestTemporaryFullAccuracy(purposeKey: string): Promise<AccuracyAuthorization>;
+    addGeofence(geofence: Geofence): Promise<boolean>;
+    addGeofences(geofences: Geofence[]): Promise<boolean>;
+    removeGeofence(identifier: string): Promise<boolean>;
+    removeGeofences(identifiers?: string[]): Promise<boolean>;
+    getGeofences(): Promise<Geofence[]>;
+    getGeofence(identifier: string): Promise<Geofence>;
+    geofenceExists(identifier: string): Promise<boolean>;
+    startSchedule(): Promise<void>;
+    stopSchedule(): Promise<void>;
+    setLogLevel(level: LogLevel): Promise<void>;
+    setLogPersist(mode: PersistMode): Promise<void>;
+    getDeviceInfo(): Promise<DeviceInfo>;
+    getSensors(): Promise<Sensors>;
+    isPowerSaveMode(): Promise<boolean>;
+    destroyLocations(): Promise<void>;
+    destroyLocation(uuid: string): Promise<void>;
+    insertLocation(location: Location): Promise<Location>;
+    getLocations(): Promise<Array<Object>>;
+    getCount(): Promise<number>;
+    sync(): Promise<Array<Object>>;
+    startBackgroundTask(): Promise<number>;
+    stopBackgroundTask(taskId: number): Promise<void>;
+    finishHeadlessTask(taskId: string): Promise<number>;
+}
 export interface BackgroundGeolocation extends BackgroundGeolocationAPI {
-    /**
-     * __LogLevel__
-     * Controls verbosity of the SDK logger.
-     * Used by LoggerConfig.logLevel.
-     * Values range from silent (`Off`) to extremely verbose (`Verbose`).
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   logger: {
-     *     logLevel: BackgroundGeolocation.LogLevel.Verbose
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     LogLevel: typeof import('../../enums/LogLevel').LogLevel;
-    /**
-     * __DesiredAccuracy__
-     * Controls the native location engine’s target accuracy.
-     * Higher accuracy consumes more battery.
-     * Used by GeoConfig.desiredAccuracy.
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   geolocation: {
-     *     desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     DesiredAccuracy: typeof import('../../enums/DesiredAccuracy').DesiredAccuracy;
-    /**
-     * __PersistMode__
-     * Controls which records the SDK persists to SQLite:
-     * locations only, geofences only, both, or none.
-     * Used by PersistenceConfig.persistMode.
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   persistence: {
-     *     persistMode: BackgroundGeolocation.PersistMode.All
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     PersistMode: typeof import('../../enums/PersistMode').PersistMode;
-    /**
-     * __AuthorizationStrategy__
-     * Defines how the HTTP service performs authorization.
-     * Includes basic, JWT, and custom strategies.
-     * Used by AuthorizationConfig.strategy.
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   authorization: {
-     *     strategy: BackgroundGeolocation.AuthorizationStrategy.Jwt
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     AuthorizationStrategy: typeof import('../../enums/AuthorizationStrategy').AuthorizationStrategy;
-    /**
-     * __LocationFilterPolicy__
-     * Selects the filtering engine policy for noise-reduction and smoothing.
-     * Used by GeoConfig.locationFilter.
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   geolocation: {
-     *     filter: {
-     *       policy: BackgroundGeolocation.LocationFilterPolicy.Adjust
-     *     }
-     * });
-     * ```
-     * @readonly
-     */
     LocationFilterPolicy: typeof import('../../enums/LocationFilterPolicy').LocationFilterPolicy;
-    /**
-     * __KalmanProfile__
-     * Selects a preset tuning profile for the Kalman filter used in the
-     * filtering engine (aggressive, moderate, or relaxed smoothing).
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   geolocation: {
-     *     kalmanProfile: BackgroundGeolocation.KalmanProfile.Aggressive
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     KalmanProfile: typeof import('../../enums/KalmanProfile').KalmanProfile;
-    /**
-     * __HttpMethod__
-     * Defines the HTTP method used for uploads (POST, PUT, etc).
-     * Used by HttpConfig.method.
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   http: {
-     *     method: BackgroundGeolocation.HttpMethod.Post
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     HttpMethod: typeof import('../../enums/HttpMethod').HttpMethod;
-    /**
-     * __TriggerActivity__
-     * Defines which physical motion activities can trigger motion-detection
-     * transitions (still → moving).
-     * Used by ActivityConfig.triggerActivities.
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   activity: {
-     *     triggerActivities: [
-     *       BackgroundGeolocation.TriggerActivity.InVehicle
-     *     ]
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     TriggerActivity: typeof import('../../enums/TriggerActivity').TriggerActivity;
-    /**
-     * __NotificationPriority__
-     * Controls Android foreground-service notification priority and icon
-     * placement (top, bottom, hidden).
-     * Used by NotificationConfig.priority.
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   notification: {
-     *     priority: BackgroundGeolocation.NotificationPriority.High
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     NotificationPriority: typeof import('../../enums/NotificationPriority').NotificationPriority;
-    /**
-     * __Event__
-     * Enumerates all event names emitted by the SDK (location, geofence,
-     * motionchange, heartbeat, etc).
-     *
-     * @readonly
-     */
     Event: typeof import('../../enums/Event').Event;
-    /**
-     * __LocationRequest__
-     * Defines the type of permission request made to iOS (Always, WhenInUse,
-     * or Any).
-     * Used by GeoConfig.locationAuthorizationRequest.
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.ready({
-     *   geolocation: {
-     *     locationAuthorizationRequest: BackgroundGeolocation.LocationRequest.Always
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     LocationRequest: typeof import('../../enums/LocationRequest').LocationRequest;
-    /**
-     * __AccuracyAuthorization__
-     * iOS 14+: Indicates whether the user granted full or reduced accuracy.
-     * Used by ProviderChangeEvent.accuracyAuthorization and
-     * requestTemporaryFullAccuracy.
-     *
-     * @example
-     * ```ts
-     * BackgroundGeolocation.onProviderChange((event) => {
-     *   if (event.accuracyAuthorization ===
-     *       BackgroundGeolocation.AccuracyAuthorization.Reduced) {
-     *     // Handle reduced-accuracy case
-     *   }
-     * });
-     * ```
-     * @readonly
-     */
     AccuracyAuthorization: typeof import('../../enums/AccuracyAuthorization').AccuracyAuthorization;
-    /**
-     * __AuthorizationStatus__
-     * Represents OS-level authorization state for location-services
-     * (Denied, Restricted, Always, WhenInUse).
-     * Returned from requestPermission() and onProviderChange.
-     *
-     * @example
-     * ```ts
-     * const status = await BackgroundGeolocation.requestPermission();
-     * if (status === BackgroundGeolocation.AuthorizationStatus.Always) {
-     *   // Good to start tracking
-     * }
-     * ```
-     * @readonly
-     */
     AuthorizationStatus: typeof import('../../enums/AuthorizationStatus').AuthorizationStatus;
+    ActivityType: typeof import('../../enums/ActivityType').ActivityType;
 }

package/dist/core/api/CurrentPositionRequest.d.ts

@@ -1,44 +1,8 @@
-/**
- * Options provided to {@link BackgroundGeolocation.getCurrentPosition}.
- *
- * @example
- * ```typescript
- * let location = await BackgroundGeolocation.getCurrentPosition({
- *   timeout: 30,          // 30 second timeout to fetch location
- *   persist: true,        // Defaults to state.enabled
- *   maximumAge: 5000,     // Accept the last-known-location if not older than 5000 ms.
- *   desiredAccuracy: 10,  // Try to fetch a location with an accuracy of `10` meters.
- *   samples: 3,           // How many location samples to attempt.
- *   extras: {             // Custom meta-data.
- *     "route_id": 123
- *   }
- * });
- * ```
- * @category Primary API
- */
 export interface CurrentPositionRequest {
-    /**
-    * Sets the maximum number of location-samples to fetch before returning the best possible location to your `callback`.  Default is `3`.  Only the final Location will be persisted.
-    */
     samples?: number;
-    /**
-    * Sets the desired accuracy of location you're attempting to fetch. When a location having `accuracy <= desiredAccuracy` is retrieved, the plugin will stop sampling and immediately return that location. Defaults to your configured [[Config.stationaryRadius]].
-    */
     desiredAccuracy?: number;
-    /**
-    * Location-timeout in `seconds`.  Default: `30`.  If the timeout expires before a [[Location]] is retrieved, a [[LocationError]] will fire.
-    */
     timeout?: number;
-    /**
-    * Defaults to `true` when plugin is `enabled`; `false`, otherwise.  Set `false` to disable persisting the retrieved Location in the plugin's SQLite database.
-    */
     persist?: boolean;
-    /**
-    * Accept the last-recorded-location if no older than supplied value in `milliseconds`.  Default is `0`.
-    */
     maximumAge?: number;
-    /**
-    * Optional meta-data to attach to the location. These `extras` will be merged to the configured [[Config.extras]] and persisted / POSTed to your server (if you've configured a [[Config.url]].
-    */
     extras?: Record<string, any>;
 }

package/dist/core/api/DeviceSettings.d.ts

@@ -1,77 +1,14 @@
-/**
- * An object for redirecting a User to an Android device's settings screen from a {@link DeviceSettings} request.
- *
- * Contains meta-data about the device (`manufacturer`, `model`, `version`) and whether you’ve already shown this screen.
- *
- * @category Device
- */
 export interface DeviceSettingsRequest {
-    /** Device manufacturer (e.g., "Huawei", "Samsung"). */
     manufacturer: string;
-    /** Device model (e.g., "P40", "SM-G991B"). */
     model: string;
-    /** OS version string. */
     version: string;
-    /** Whether this screen has previously been shown. */
     seen: boolean;
-    /** Timestamp of when this screen was last shown. */
     lastSeenAt: Date;
-    /**
-     * The settings screen action to be shown.
-     * ⚠️ Set automatically by the native layer.
-     */
     action: string;
 }
-/**
- * Device Settings API (types-only).
- *
- * Provides an API to show Android & vendor-specific Battery / Power Management settings screens that can
- * affect performance of the Background Geolocation SDK on various devices.
- *
- * See: https://dontkillmyapp.com/
- *
- * @example
- * ```ts
- * // Is Android device ignoring battery optimizations?
- * const isIgnoring = await BackgroundGeolocation.deviceSettings.isIgnoringBatteryOptimizations();
- * if (!isIgnoring) {
- *   const req = await BackgroundGeolocation.deviceSettings.showIgnoreBatteryOptimizations();
- *   if (!req.seen) {
- *     const confirmed = await showMyConfirmDialog({ title: 'Settings request', text: 'Please disable battery optimizations' });
- *     if (confirmed) {
- *       await BackgroundGeolocation.deviceSettings.show(req);
- *     }
- *   }
- * }
- * ```
- * @category Device
- */
 export interface DeviceSettings {
-    /**
-     * Returns `true` if device is ignoring battery optimizations for your app.
-     *
-     * In most cases, the SDK performs normally with battery optimizations enabled.
-     */
     isIgnoringBatteryOptimizations(): Promise<boolean>;
-    /**
-     * Prepare a request to show Android’s *Ignore Battery Optimizations* settings screen.
-     *
-     * Does **not** immediately redirect — returns a {@link DeviceSettingsRequest} first so you can
-     * decide whether to prompt the user (eg: avoid annoying them if `seen === true`).
-     *
-     * ⚠️ On some devices/OS versions, this screen may not exist; callers should `catch` errors.
-     */
     showIgnoreBatteryOptimizations(): Promise<DeviceSettingsRequest>;
-    /**
-     * Prepare a request to show a vendor-specific “Power Manager” screen (Huawei, Xiaomi, Vivo, etc).
-     *
-     * Does **not** immediately redirect — returns a {@link DeviceSettingsRequest} first.
-     * Not all vendors/versions implement this screen; callers should `catch` errors.
-     */
     showPowerManager(): Promise<DeviceSettingsRequest>;
-    /**
-     * Execute a previously prepared {@link DeviceSettingsRequest} to actually show the screen.
-     * Resolves `true` if the redirect was attempted.
-     */
     show(request: DeviceSettingsRequest): Promise<boolean>;
 }