@bglocation/capacitor 1.1.0

package/dist/esm/definitions.d.ts

@@ -0,0 +1,390 @@
+import type { PermissionState, PluginListenerHandle } from '@capacitor/core';
+export type LocationPermissionType = 'location' | 'backgroundLocation';
+export interface LocationPermissionStatus {
+    /** Foreground location permission (ACCESS_FINE_LOCATION / When In Use). */
+    location: PermissionState;
+    /** Background location permission (ACCESS_BACKGROUND_LOCATION / Always). */
+    backgroundLocation: PermissionState;
+}
+export interface LocationPermissionRequest {
+    permissions: LocationPermissionType[];
+}
+export interface BackgroundLocationPlugin {
+    /**
+     * Get plugin and native core version information.
+     */
+    getVersion(): Promise<VersionInfo>;
+    /**
+     * Check the current status of location permissions.
+     */
+    checkPermissions(): Promise<LocationPermissionStatus>;
+    /**
+     * Request location permissions from the user.
+     * On Android 10+, background location must be requested separately after foreground is granted.
+     * Pass `{ permissions: ['location'] }` first, then `{ permissions: ['backgroundLocation'] }`.
+     */
+    requestPermissions(options?: LocationPermissionRequest): Promise<LocationPermissionStatus>;
+    /**
+     * Configure the background location service.
+     * Must be called before start().
+     * Returns license validation result.
+     */
+    configure(options: LocationConfig): Promise<ConfigureResult>;
+    /**
+     * Start background location tracking.
+     * Requires location permissions to be granted.
+     */
+    start(): Promise<LocationState>;
+    /**
+     * Stop background location tracking.
+     */
+    stop(): Promise<LocationState>;
+    /**
+     * Get the current state of the location service.
+     */
+    getState(): Promise<LocationState>;
+    /**
+     * Request a single location update.
+     */
+    getCurrentPosition(options?: PositionOptions): Promise<Location>;
+    /**
+     * Listen for location updates.
+     */
+    addListener(event: 'onLocation', handler: (location: Location) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for heartbeat events (fired at heartbeatInterval when stationary).
+     */
+    addListener(event: 'onHeartbeat', handler: (event: HeartbeatEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for location provider changes (GPS on/off).
+     */
+    addListener(event: 'onProviderChange', handler: (event: ProviderChangeEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for HTTP responses from native location uploads.
+     * Only emitted when `http` is configured in LocationConfig.
+     */
+    addListener(event: 'onHttp', handler: (event: HttpEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for debug log messages.
+     * Only emitted when `debug: true` is set in LocationConfig.
+     */
+    addListener(event: 'onDebug', handler: (event: DebugEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for battery optimization warnings (Android only).
+     * Emitted on start() if the device has active battery optimization that may kill tracking.
+     * Includes OEM-specific help URL (dontkillmyapp.com).
+     * On iOS/Web this event is never emitted.
+     */
+    addListener(event: 'onBatteryWarning', handler: (event: BatteryWarningEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for accuracy authorization warnings (iOS only).
+     * Emitted on start() if the user has granted only approximate location (iOS 14+).
+     * On Android/Web this event is never emitted.
+     */
+    addListener(event: 'onAccuracyWarning', handler: (event: AccuracyWarningEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for mock location detection (Android only).
+     * Emitted when a location from a mock provider is detected.
+     * On iOS/Web this event is never emitted.
+     */
+    addListener(event: 'onMockLocation', handler: (event: MockLocationEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for permission rationale events (Android 11+ only).
+     * Emitted before requesting background location permission, so the app
+     * can display a custom rationale UI explaining why "Allow all the time" is needed.
+     * On iOS/Web this event is never emitted.
+     */
+    addListener(event: 'onPermissionRationale', handler: (event: PermissionRationaleEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for trial expiration events.
+     * Emitted when the 30-minute trial period expires — tracking is auto-stopped.
+     * Only emitted in trial mode (no valid license key).
+     * On Web this event is never emitted.
+     */
+    addListener(event: 'onTrialExpired', handler: (event: TrialExpiredEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Add a geofence region to monitor.
+     * Requires `configure()` to be called first — rejects with `'NOT_CONFIGURED'` otherwise.
+     * Rejects with `'GEOFENCE_LIMIT_EXCEEDED'` if adding would exceed the 20-geofence limit.
+     * If a geofence with the same `identifier` already exists, it is replaced (not an error).
+     * On Web: rejects with `'UNSUPPORTED'`.
+     */
+    addGeofence(geofence: Geofence): Promise<void>;
+    /**
+     * Add multiple geofence regions atomically (all-or-nothing).
+     * If the total count would exceed 20, the entire batch is rejected.
+     * Requires `configure()` to be called first.
+     * On Web: rejects with `'UNSUPPORTED'`.
+     */
+    addGeofences(options: {
+        geofences: Geofence[];
+    }): Promise<void>;
+    /**
+     * Remove a geofence region by its identifier.
+     * No-op if the identifier does not match any registered geofence.
+     * On Web: rejects with `'UNSUPPORTED'`.
+     */
+    removeGeofence(options: {
+        identifier: string;
+    }): Promise<void>;
+    /**
+     * Remove all registered geofence regions.
+     * On Web: rejects with `'UNSUPPORTED'`.
+     */
+    removeAllGeofences(): Promise<void>;
+    /**
+     * Get the list of currently registered geofences.
+     * Returns data from the persistence layer (source of truth).
+     * On Web: rejects with `'UNSUPPORTED'`.
+     */
+    getGeofences(): Promise<{
+        geofences: Geofence[];
+    }>;
+    /**
+     * Listen for geofence transition events (enter, exit, dwell).
+     * Emitted on both iOS and Android, even when the app is in background or terminated.
+     * On Web this event is never emitted.
+     */
+    addListener(event: 'onGeofence', handler: (event: GeofenceEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Check if battery optimization is affecting this app (Android only).
+     * Returns the current battery optimization state and OEM-specific info.
+     * On iOS/Web, returns `{ isIgnoringOptimizations: true }` (no-op).
+     */
+    checkBatteryOptimization(): Promise<BatteryWarningEvent>;
+    /**
+     * Open the system battery optimization settings for this app (Android only).
+     * On Android: opens ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS intent.
+     * On iOS/Web: no-op, resolves immediately.
+     *
+     * NOTE: The returned `BatteryWarningEvent` reflects the state **before** the user
+     * interacts with the system dialog. Call `checkBatteryOptimization()` after the app
+     * resumes to get the updated state.
+     */
+    requestBatteryOptimization(): Promise<BatteryWarningEvent>;
+    /**
+     * Remove all registered listeners.
+     */
+    removeAllListeners(): Promise<void>;
+}
+export interface HttpConfig {
+    /** The URL to POST location data to. */
+    url: string;
+    /** Optional HTTP headers (e.g. Authorization). */
+    headers?: Record<string, string>;
+    /**
+     * Offline buffer configuration. When enabled, failed HTTP requests are
+     * stored in a local SQLite database and retried automatically.
+     */
+    buffer?: LocationBufferConfig;
+}
+export interface LocationBufferConfig {
+    /** Maximum number of locations to store in the offline buffer. Oldest entries are dropped when exceeded. @default 1000 */
+    maxSize?: number;
+}
+export interface NotificationConfig {
+    /** Title of the Android foreground service notification. @default 'Background Location' */
+    title?: string;
+    /** Text body of the Android foreground service notification. @default 'Tracking your location' */
+    text?: string;
+}
+export interface AutoDistanceFilterConfig {
+    /** Target interval between location updates in seconds. @default 10 */
+    targetInterval?: number;
+    /** Minimum distance filter in meters (prevents excessive updates at low speed). @default 10 */
+    minDistance?: number;
+    /** Maximum distance filter in meters (ensures updates even at high speed). @default 500 */
+    maxDistance?: number;
+}
+export interface LocationConfig {
+    /** Distance filter in meters, or 'auto' for speed-adaptive mode. @default 15 */
+    distanceFilter?: number | 'auto';
+    /** Configuration for auto distance filter mode. Only used when distanceFilter is 'auto'. */
+    autoDistanceFilter?: AutoDistanceFilterConfig;
+    /** Location update interval in **milliseconds** (Android only). @default 5000 */
+    locationUpdateInterval?: number;
+    /** Fastest location update interval in **milliseconds** (Android only). @default 2000 */
+    fastestLocationUpdateInterval?: number;
+    /** Heartbeat interval in **seconds** when stationary. Applied identically on all platforms. @default 15 */
+    heartbeatInterval?: number;
+    /** Desired accuracy level. @default 'high' */
+    desiredAccuracy?: 'high' | 'balanced' | 'low';
+    /** Optional HTTP config. When provided, location updates are POSTed natively to the given URL. */
+    http?: HttpConfig;
+    /**
+     * Android foreground service notification configuration.
+     * Allows customizing the persistent notification title and text (i18n ready).
+     * Has no effect on iOS (uses blue pill indicator) or Web.
+     */
+    notification?: NotificationConfig;
+    /**
+     * Enable debug mode. When true:
+     * - Verbose native logging (os_log on iOS, Logcat on Android)
+     * - `onDebug` events emitted to JS with timestamped messages
+     * - Android: notification updated dynamically with coordinates, counters, status
+     * - Optional system sounds on key events (location fix, heartbeat, HTTP)
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Play system sounds on key events in debug mode.
+     * Only applies when `debug: true`.
+     * @default false
+     */
+    debugSounds?: boolean;
+}
+export interface Location {
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+    speed: number;
+    heading: number;
+    altitude: number;
+    timestamp: number;
+    isMoving: boolean;
+    /** Whether this location was generated by a mock provider (Android only). Always `false` on iOS/Web. */
+    isMock: boolean;
+    /** Current effective distance filter in meters. Only present when distanceFilter is 'auto'. */
+    effectiveDistanceFilter?: number;
+}
+export interface LocationState {
+    /** Whether location permission is granted (iOS: authorization status, Android: runtime permission). */
+    enabled: boolean;
+    /** Whether the plugin is actively tracking location. */
+    tracking: boolean;
+}
+export interface HeartbeatEvent {
+    /** Location at the time of heartbeat. `null` if no location has been acquired yet (cold start). */
+    location: Location | null;
+    /** Epoch milliseconds when this heartbeat fired (independent of location timestamp). */
+    timestamp: number;
+}
+export interface ProviderChangeEvent {
+    gps: boolean;
+    network: boolean;
+    enabled: boolean;
+    status: number;
+}
+export interface HttpEvent {
+    /** HTTP status code (0 if network error). */
+    statusCode: number;
+    /** Whether the request succeeded (2xx). */
+    success: boolean;
+    /** Response body text. */
+    responseText: string;
+    /** Error message if the request failed due to a network error. */
+    error?: string;
+    /** Number of locations currently waiting in the offline buffer. 0 when buffer is disabled or empty. */
+    bufferedCount?: number;
+}
+export interface DebugEvent {
+    /** Debug log message. */
+    message: string;
+    /** Epoch milliseconds when this debug event was generated. */
+    timestamp: number;
+}
+export interface PositionOptions {
+    timeout?: number;
+}
+export interface BatteryWarningEvent {
+    /** Whether the app is exempt from battery optimization (true = safe, false = at risk). */
+    isIgnoringOptimizations: boolean;
+    /** Device manufacturer in lowercase (e.g., 'xiaomi', 'huawei', 'samsung'). Empty on iOS/Web. */
+    manufacturer: string;
+    /** URL to dontkillmyapp.com with OEM-specific instructions. Empty when not applicable. */
+    helpUrl: string;
+    /** Human-readable warning message. */
+    message: string;
+}
+export interface AccuracyWarningEvent {
+    /** Current accuracy authorization: 'full' (precise GPS) or 'approximate' (degraded). */
+    accuracyAuthorization: 'full' | 'approximate';
+    /** Human-readable warning message. */
+    message: string;
+}
+export interface MockLocationEvent {
+    /** The mock location that was detected. */
+    location: Location;
+    /** Human-readable warning message. */
+    message: string;
+}
+export interface PermissionRationaleEvent {
+    /** The permission that requires rationale before requesting. */
+    permission: 'backgroundLocation';
+    /** Whether the system suggests showing a rationale (Android `shouldShowRequestPermissionRationale`). */
+    shouldShowRationale: boolean;
+    /** Human-readable message explaining why the permission is needed. */
+    message: string;
+}
+/** License validation result returned by configure(). */
+export interface ConfigureResult {
+    /** Current license mode: 'full' (no restrictions) or 'trial' (debug=true, 30 min limit, 1h cooldown). */
+    licenseMode: 'full' | 'trial';
+    /** The distance filter mode in effect: 'fixed' or 'auto'. */
+    distanceFilterMode: 'fixed' | 'auto';
+    /** ISO 8601 date until which plugin updates are available. Only present when licenseMode is 'full' and exp is set in key. */
+    licenseUpdatesUntil?: string;
+    /** Whether the license key's update period has expired for this plugin version. When true, the plugin degrades to trial mode. Renew at bglocation.dev/portal. */
+    licenseUpdateExpired?: boolean;
+    /** Reason the license key was rejected. Only present when licenseMode is 'trial'. */
+    licenseError?: string;
+}
+/** Emitted when the trial period expires (30 min). */
+export interface TrialExpiredEvent {
+    /** Duration in seconds that tracking was active before expiry. */
+    elapsed: number;
+    /** Cooldown duration in seconds before next start() is allowed. */
+    cooldownSeconds: number;
+    /** Human-readable message. */
+    message: string;
+}
+/** Error returned when start() is called during trial cooldown. */
+export interface TrialCooldownError {
+    /** Remaining cooldown time in seconds. */
+    remainingSeconds: number;
+    /** Human-readable message. */
+    message: string;
+}
+/** Plugin and native core version information. */
+export interface VersionInfo {
+    /** Plugin version (from package.json). */
+    pluginVersion: string;
+    /** Native core library version. */
+    coreVersion: string;
+}
+/** Maximum number of geofences that can be registered simultaneously (iOS CLLocationManager limit). */
+export declare const GEOFENCE_MAX_COUNT = 20;
+/** Configuration for a single geofence region. */
+export interface Geofence {
+    /** Unique identifier for this geofence. Used to remove or replace it. */
+    identifier: string;
+    /** Center latitude in degrees. */
+    latitude: number;
+    /** Center longitude in degrees. */
+    longitude: number;
+    /** Radius in meters. Recommended minimum: 100m for reliable detection. */
+    radius: number;
+    /** Fire event when entering the region. @default true */
+    notifyOnEntry?: boolean;
+    /** Fire event when exiting the region. @default true */
+    notifyOnExit?: boolean;
+    /** Fire event after dwelling in the region for `dwellDelay` seconds. **iOS: not supported natively by Core Location — this flag is accepted but ignored.** @default false */
+    notifyOnDwell?: boolean;
+    /** Seconds to wait inside region before firing a dwell event. Only effective on Android. @default 300 */
+    dwellDelay?: number;
+    /** Optional payload data attached to geofence events. Values must be strings (stringify numbers/booleans). */
+    extras?: Record<string, string>;
+}
+/** Event emitted when a geofence transition occurs. */
+export interface GeofenceEvent {
+    /** Identifier of the geofence that triggered. */
+    identifier: string;
+    /** Type of transition. */
+    action: 'enter' | 'exit' | 'dwell';
+    /** Location at the time of the transition. `null` if unavailable. */
+    location: Location | null;
+    /** Optional extras attached when the geofence was created. */
+    extras?: Record<string, string>;
+    /** Epoch milliseconds when the transition was detected. */
+    timestamp: number;
+}

package/dist/esm/definitions.js

@@ -0,0 +1,3 @@
+/** Maximum number of geofences that can be registered simultaneously (iOS CLLocationManager limit). */
+export const GEOFENCE_MAX_COUNT = 20;
+//# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAwbA,uGAAuG;AACvG,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+import type { BackgroundLocationPlugin } from './definitions';
+declare const BackgroundLocation: BackgroundLocationPlugin;
+export * from './definitions';
+export { BackgroundLocation };

package/dist/esm/index.js

@@ -0,0 +1,26 @@
+import { registerPlugin } from '@capacitor/core';
+const RawPlugin = registerPlugin('BackgroundLocation', {
+    web: () => import('./web').then((m) => new m.BackgroundLocationWeb()),
+});
+/**
+ * Thin wrapper that merges partial `configure()` calls with the last-applied
+ * config so callers don't lose previously set fields (e.g. http endpoint)
+ * when reconfiguring a single field (e.g. distanceFilter).
+ */
+let lastConfig;
+const BackgroundLocation = new Proxy(RawPlugin, {
+    get(target, prop, receiver) {
+        if (prop === 'configure') {
+            return async (options) => {
+                const merged = lastConfig ? { ...lastConfig, ...options } : options;
+                const result = await target.configure(merged);
+                lastConfig = merged;
+                return result;
+            };
+        }
+        return Reflect.get(target, prop, receiver);
+    },
+});
+export * from './definitions';
+export { BackgroundLocation };
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,SAAS,GAAG,cAAc,CAC9B,oBAAoB,EACpB;IACE,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,qBAAqB,EAAE,CAAC;CACtE,CACF,CAAC;AAEF;;;;GAIG;AACH,IAAI,UAAsC,CAAC;AAE3C,MAAM,kBAAkB,GAA6B,IAAI,KAAK,CAAC,SAAS,EAAE;IACxE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;QACxB,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YACzB,OAAO,KAAK,EAAE,OAAuB,EAA4B,EAAE;gBACjE,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;gBACpE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;gBAC9C,UAAU,GAAG,MAAM,CAAC;gBACpB,OAAO,MAAM,CAAC;YAChB,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;CACF,CAAC,CAAC;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/esm/web.d.ts

@@ -0,0 +1,47 @@
+import { WebPlugin } from '@capacitor/core';
+import type { BackgroundLocationPlugin, BatteryWarningEvent, ConfigureResult, Geofence, Location, LocationConfig, LocationPermissionStatus, LocationState, PositionOptions, VersionInfo } from './definitions';
+/**
+ * Web fallback using navigator.geolocation.
+ * Used for development/testing in the browser only.
+ */
+export declare class BackgroundLocationWeb extends WebPlugin implements BackgroundLocationPlugin {
+    private watchId;
+    private heartbeatTimer;
+    private config;
+    private httpConfig;
+    private isTracking;
+    private debug;
+    private locationCount;
+    private heartbeatCount;
+    private httpSuccessCount;
+    private httpErrorCount;
+    private geofenceStore;
+    getVersion(): Promise<VersionInfo>;
+    checkPermissions(): Promise<LocationPermissionStatus>;
+    requestPermissions(): Promise<LocationPermissionStatus>;
+    configure(options: LocationConfig): Promise<ConfigureResult>;
+    start(): Promise<LocationState>;
+    stop(): Promise<LocationState>;
+    getState(): Promise<LocationState>;
+    removeAllListeners(): Promise<void>;
+    getCurrentPosition(options?: PositionOptions): Promise<Location>;
+    checkBatteryOptimization(): Promise<BatteryWarningEvent>;
+    requestBatteryOptimization(): Promise<BatteryWarningEvent>;
+    addGeofence(geofence: Geofence): Promise<void>;
+    addGeofences(options: {
+        geofences: Geofence[];
+    }): Promise<void>;
+    removeGeofence(options: {
+        identifier: string;
+    }): Promise<void>;
+    removeAllGeofences(): Promise<void>;
+    getGeofences(): Promise<{
+        geofences: Geofence[];
+    }>;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private geolocationToLocation;
+    private sendHttp;
+    private emitDebug;
+    private resetCounters;
+}