@bglocation/capacitor 1.1.0

package/dist/plugin.js

@@ -0,0 +1,270 @@
+var capacitorBackgroundLocation = (function (exports, core) {
+    'use strict';
+
+    /** Maximum number of geofences that can be registered simultaneously (iOS CLLocationManager limit). */
+    const GEOFENCE_MAX_COUNT = 20;
+
+    const RawPlugin = core.registerPlugin('BackgroundLocation', {
+        web: () => Promise.resolve().then(function () { return 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);
+        },
+    });
+
+    /**
+     * Web fallback using navigator.geolocation.
+     * Used for development/testing in the browser only.
+     */
+    class BackgroundLocationWeb extends core.WebPlugin {
+        watchId = null;
+        heartbeatTimer = null;
+        config = null;
+        httpConfig = null;
+        isTracking = false;
+        debug = false;
+        locationCount = 0;
+        heartbeatCount = 0;
+        httpSuccessCount = 0;
+        httpErrorCount = 0;
+        geofenceStore = new Map();
+        async getVersion() {
+            return { pluginVersion: '1.1.0', coreVersion: 'web' };
+        }
+        async checkPermissions() {
+            const result = await navigator.permissions.query({ name: 'geolocation' });
+            const state = result.state === 'granted' ? 'granted' : result.state === 'denied' ? 'denied' : 'prompt';
+            // Web has no separate background permission — mirror foreground state
+            return { location: state, backgroundLocation: state };
+        }
+        async requestPermissions() {
+            // Web API doesn't have explicit requestPermissions — permission is requested on first use.
+            return this.checkPermissions();
+        }
+        async configure(options) {
+            this.config = options;
+            this.httpConfig = options.http ?? null;
+            this.debug = options.debug ?? false;
+            this.resetCounters();
+            const distanceFilter = options.distanceFilter ?? 15;
+            const heartbeatInterval = options.heartbeatInterval ?? 15;
+            const distanceFilterMode = distanceFilter === 'auto' ? 'auto' : 'fixed';
+            if (distanceFilter === 'auto') {
+                this.emitDebug('CONFIGURE distanceFilter=auto ignored on Web — browser does not support native distance filtering');
+            }
+            this.emitDebug(`CONFIGURE distance=${distanceFilter}m heartbeat=${heartbeatInterval}s http=${options.http?.url ?? 'disabled'}`);
+            console.info('[BackgroundLocation:web] configured', options);
+            return { licenseMode: 'full', distanceFilterMode };
+        }
+        async start() {
+            if (!this.config) {
+                throw new Error('Plugin not configured. Call configure() first.');
+            }
+            this.watchId = navigator.geolocation.watchPosition((position) => {
+                const location = this.geolocationToLocation(position);
+                this.notifyListeners('onLocation', location);
+                this.locationCount++;
+                this.emitDebug(`LOCATION #${this.locationCount} (${location.latitude.toFixed(5)}, ${location.longitude.toFixed(5)}) acc=${location.accuracy.toFixed(1)}m`);
+                this.sendHttp(location);
+            }, (error) => {
+                console.error('[BackgroundLocation:web] watch error:', error.message);
+            }, {
+                enableHighAccuracy: (this.config.desiredAccuracy ?? 'high') === 'high',
+                maximumAge: 1000,
+                timeout: 20000,
+            });
+            this.startHeartbeat();
+            this.isTracking = true;
+            this.resetCounters();
+            this.emitDebug('START tracking');
+            return { enabled: true, tracking: true };
+        }
+        async stop() {
+            if (this.watchId !== null) {
+                navigator.geolocation.clearWatch(this.watchId);
+                this.watchId = null;
+            }
+            this.stopHeartbeat();
+            this.isTracking = false;
+            this.emitDebug(`STOP tracking — locations=${this.locationCount} heartbeats=${this.heartbeatCount} http_ok=${this.httpSuccessCount} http_err=${this.httpErrorCount}`);
+            const permissions = await this.checkPermissions();
+            return { enabled: permissions.location === 'granted', tracking: false };
+        }
+        async getState() {
+            const permissions = await this.checkPermissions();
+            return { enabled: permissions.location === 'granted', tracking: this.isTracking };
+        }
+        async removeAllListeners() {
+            if (this.watchId !== null) {
+                navigator.geolocation.clearWatch(this.watchId);
+                this.watchId = null;
+            }
+            this.stopHeartbeat();
+            this.isTracking = false;
+            await super.removeAllListeners();
+        }
+        async getCurrentPosition(options) {
+            return new Promise((resolve, reject) => {
+                navigator.geolocation.getCurrentPosition((position) => resolve(this.geolocationToLocation(position)), (error) => reject(new Error(error.message)), { enableHighAccuracy: true, timeout: options?.timeout ?? 20000 });
+            });
+        }
+        // B.1: Battery optimization — no-op on Web (not applicable to browsers)
+        async checkBatteryOptimization() {
+            return {
+                isIgnoringOptimizations: true,
+                manufacturer: '',
+                helpUrl: '',
+                message: 'Battery optimization is not applicable on Web platform.',
+            };
+        }
+        async requestBatteryOptimization() {
+            return this.checkBatteryOptimization();
+        }
+        // -----------------------------------------------------------------------
+        // Geofencing — in-memory stub for development/testing
+        // -----------------------------------------------------------------------
+        async addGeofence(geofence) {
+            if (this.geofenceStore.size >= GEOFENCE_MAX_COUNT && !this.geofenceStore.has(geofence.identifier)) {
+                throw new Error(`Geofence limit reached (max ${GEOFENCE_MAX_COUNT})`);
+            }
+            this.geofenceStore.set(geofence.identifier, { ...geofence });
+            this.emitDebug(`[GEOFENCE ADD] "${geofence.identifier}" (${this.geofenceStore.size}/${GEOFENCE_MAX_COUNT})`);
+        }
+        async addGeofences(options) {
+            for (const geofence of options.geofences) {
+                await this.addGeofence(geofence);
+            }
+        }
+        async removeGeofence(options) {
+            if (!this.geofenceStore.has(options.identifier)) {
+                throw new Error(`Geofence "${options.identifier}" not found`);
+            }
+            this.geofenceStore.delete(options.identifier);
+            this.emitDebug(`[GEOFENCE REMOVE] "${options.identifier}" (${this.geofenceStore.size}/${GEOFENCE_MAX_COUNT})`);
+        }
+        async removeAllGeofences() {
+            const count = this.geofenceStore.size;
+            this.geofenceStore.clear();
+            this.emitDebug(`[GEOFENCE REMOVE_ALL] removed ${count}`);
+        }
+        async getGeofences() {
+            return { geofences: Array.from(this.geofenceStore.values()) };
+        }
+        startHeartbeat() {
+            if (!this.config)
+                return;
+            this.heartbeatTimer = setInterval(() => {
+                navigator.geolocation.getCurrentPosition((position) => {
+                    const location = this.geolocationToLocation(position);
+                    this.notifyListeners('onHeartbeat', { location, timestamp: Date.now() });
+                    this.heartbeatCount++;
+                    this.emitDebug(`HEARTBEAT #${this.heartbeatCount} with location`);
+                }, (_error) => {
+                    // Emit heartbeat with null location to match native platform behavior
+                    this.notifyListeners('onHeartbeat', { location: null, timestamp: Date.now() });
+                    this.heartbeatCount++;
+                    this.emitDebug(`HEARTBEAT #${this.heartbeatCount} no location`);
+                });
+            }, (this.config.heartbeatInterval ?? 15) * 1000);
+        }
+        stopHeartbeat() {
+            if (this.heartbeatTimer !== null) {
+                clearInterval(this.heartbeatTimer);
+                this.heartbeatTimer = null;
+            }
+        }
+        geolocationToLocation(position) {
+            return {
+                latitude: position.coords.latitude,
+                longitude: position.coords.longitude,
+                accuracy: position.coords.accuracy,
+                speed: position.coords.speed ?? 0,
+                heading: position.coords.heading ?? -1,
+                altitude: position.coords.altitude ?? 0,
+                timestamp: position.timestamp,
+                isMoving: (position.coords.speed ?? 0) > 0.5,
+                isMock: false,
+            };
+        }
+        sendHttp(location) {
+            if (!this.httpConfig)
+                return;
+            const headers = {
+                'Content-Type': 'application/json',
+                ...(this.httpConfig.headers ?? {}),
+            };
+            fetch(this.httpConfig.url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ location }),
+            })
+                .then(async (response) => {
+                const responseText = await response.text().catch(() => '');
+                if (response.ok) {
+                    this.httpSuccessCount++;
+                    this.emitDebug(`HTTP OK #${this.httpSuccessCount} status=${response.status}`);
+                }
+                else {
+                    this.httpErrorCount++;
+                    this.emitDebug(`HTTP ERROR #${this.httpErrorCount} status=${response.status}`);
+                }
+                this.notifyListeners('onHttp', {
+                    statusCode: response.status,
+                    success: response.ok,
+                    responseText,
+                    bufferedCount: 0,
+                });
+            })
+                .catch((error) => {
+                this.httpErrorCount++;
+                this.emitDebug(`HTTP ERROR #${this.httpErrorCount} status=0 error=${error.message}`);
+                this.notifyListeners('onHttp', {
+                    statusCode: 0,
+                    success: false,
+                    responseText: '',
+                    error: error.message,
+                    bufferedCount: 0,
+                });
+            });
+        }
+        emitDebug(message) {
+            if (!this.debug)
+                return;
+            console.debug(`[BGL_DEBUG] ${message}`);
+            this.notifyListeners('onDebug', { message, timestamp: Date.now() });
+        }
+        resetCounters() {
+            this.locationCount = 0;
+            this.heartbeatCount = 0;
+            this.httpSuccessCount = 0;
+            this.httpErrorCount = 0;
+        }
+    }
+
+    var web = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        BackgroundLocationWeb: BackgroundLocationWeb
+    });
+
+    exports.BackgroundLocation = BackgroundLocation;
+    exports.GEOFENCE_MAX_COUNT = GEOFENCE_MAX_COUNT;
+
+    return exports;
+
+})({}, capacitorExports);
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sources":["esm/definitions.js","esm/index.js","esm/web.js"],"sourcesContent":["/** Maximum number of geofences that can be registered simultaneously (iOS CLLocationManager limit). */\nexport const GEOFENCE_MAX_COUNT = 20;\n//# sourceMappingURL=definitions.js.map","import { registerPlugin } from '@capacitor/core';\nconst RawPlugin = registerPlugin('BackgroundLocation', {\n    web: () => import('./web').then((m) => new m.BackgroundLocationWeb()),\n});\n/**\n * Thin wrapper that merges partial `configure()` calls with the last-applied\n * config so callers don't lose previously set fields (e.g. http endpoint)\n * when reconfiguring a single field (e.g. distanceFilter).\n */\nlet lastConfig;\nconst BackgroundLocation = new Proxy(RawPlugin, {\n    get(target, prop, receiver) {\n        if (prop === 'configure') {\n            return async (options) => {\n                const merged = lastConfig ? { ...lastConfig, ...options } : options;\n                const result = await target.configure(merged);\n                lastConfig = merged;\n                return result;\n            };\n        }\n        return Reflect.get(target, prop, receiver);\n    },\n});\nexport * from './definitions';\nexport { BackgroundLocation };\n//# sourceMappingURL=index.js.map","import { WebPlugin } from '@capacitor/core';\nimport { GEOFENCE_MAX_COUNT } from './definitions';\n/**\n * Web fallback using navigator.geolocation.\n * Used for development/testing in the browser only.\n */\nexport class BackgroundLocationWeb extends WebPlugin {\n    watchId = null;\n    heartbeatTimer = null;\n    config = null;\n    httpConfig = null;\n    isTracking = false;\n    debug = false;\n    locationCount = 0;\n    heartbeatCount = 0;\n    httpSuccessCount = 0;\n    httpErrorCount = 0;\n    geofenceStore = new Map();\n    async getVersion() {\n        return { pluginVersion: '1.1.0', coreVersion: 'web' };\n    }\n    async checkPermissions() {\n        const result = await navigator.permissions.query({ name: 'geolocation' });\n        const state = result.state === 'granted' ? 'granted' : result.state === 'denied' ? 'denied' : 'prompt';\n        // Web has no separate background permission — mirror foreground state\n        return { location: state, backgroundLocation: state };\n    }\n    async requestPermissions() {\n        // Web API doesn't have explicit requestPermissions — permission is requested on first use.\n        return this.checkPermissions();\n    }\n    async configure(options) {\n        this.config = options;\n        this.httpConfig = options.http ?? null;\n        this.debug = options.debug ?? false;\n        this.resetCounters();\n        const distanceFilter = options.distanceFilter ?? 15;\n        const heartbeatInterval = options.heartbeatInterval ?? 15;\n        const distanceFilterMode = distanceFilter === 'auto' ? 'auto' : 'fixed';\n        if (distanceFilter === 'auto') {\n            this.emitDebug('CONFIGURE distanceFilter=auto ignored on Web — browser does not support native distance filtering');\n        }\n        this.emitDebug(`CONFIGURE distance=${distanceFilter}m heartbeat=${heartbeatInterval}s http=${options.http?.url ?? 'disabled'}`);\n        console.info('[BackgroundLocation:web] configured', options);\n        return { licenseMode: 'full', distanceFilterMode };\n    }\n    async start() {\n        if (!this.config) {\n            throw new Error('Plugin not configured. Call configure() first.');\n        }\n        this.watchId = navigator.geolocation.watchPosition((position) => {\n            const location = this.geolocationToLocation(position);\n            this.notifyListeners('onLocation', location);\n            this.locationCount++;\n            this.emitDebug(`LOCATION #${this.locationCount} (${location.latitude.toFixed(5)}, ${location.longitude.toFixed(5)}) acc=${location.accuracy.toFixed(1)}m`);\n            this.sendHttp(location);\n        }, (error) => {\n            console.error('[BackgroundLocation:web] watch error:', error.message);\n        }, {\n            enableHighAccuracy: (this.config.desiredAccuracy ?? 'high') === 'high',\n            maximumAge: 1000,\n            timeout: 20000,\n        });\n        this.startHeartbeat();\n        this.isTracking = true;\n        this.resetCounters();\n        this.emitDebug('START tracking');\n        return { enabled: true, tracking: true };\n    }\n    async stop() {\n        if (this.watchId !== null) {\n            navigator.geolocation.clearWatch(this.watchId);\n            this.watchId = null;\n        }\n        this.stopHeartbeat();\n        this.isTracking = false;\n        this.emitDebug(`STOP tracking — locations=${this.locationCount} heartbeats=${this.heartbeatCount} http_ok=${this.httpSuccessCount} http_err=${this.httpErrorCount}`);\n        const permissions = await this.checkPermissions();\n        return { enabled: permissions.location === 'granted', tracking: false };\n    }\n    async getState() {\n        const permissions = await this.checkPermissions();\n        return { enabled: permissions.location === 'granted', tracking: this.isTracking };\n    }\n    async removeAllListeners() {\n        if (this.watchId !== null) {\n            navigator.geolocation.clearWatch(this.watchId);\n            this.watchId = null;\n        }\n        this.stopHeartbeat();\n        this.isTracking = false;\n        await super.removeAllListeners();\n    }\n    async getCurrentPosition(options) {\n        return new Promise((resolve, reject) => {\n            navigator.geolocation.getCurrentPosition((position) => resolve(this.geolocationToLocation(position)), (error) => reject(new Error(error.message)), { enableHighAccuracy: true, timeout: options?.timeout ?? 20000 });\n        });\n    }\n    // B.1: Battery optimization — no-op on Web (not applicable to browsers)\n    async checkBatteryOptimization() {\n        return {\n            isIgnoringOptimizations: true,\n            manufacturer: '',\n            helpUrl: '',\n            message: 'Battery optimization is not applicable on Web platform.',\n        };\n    }\n    async requestBatteryOptimization() {\n        return this.checkBatteryOptimization();\n    }\n    // -----------------------------------------------------------------------\n    // Geofencing — in-memory stub for development/testing\n    // -----------------------------------------------------------------------\n    async addGeofence(geofence) {\n        if (this.geofenceStore.size >= GEOFENCE_MAX_COUNT && !this.geofenceStore.has(geofence.identifier)) {\n            throw new Error(`Geofence limit reached (max ${GEOFENCE_MAX_COUNT})`);\n        }\n        this.geofenceStore.set(geofence.identifier, { ...geofence });\n        this.emitDebug(`[GEOFENCE ADD] \"${geofence.identifier}\" (${this.geofenceStore.size}/${GEOFENCE_MAX_COUNT})`);\n    }\n    async addGeofences(options) {\n        for (const geofence of options.geofences) {\n            await this.addGeofence(geofence);\n        }\n    }\n    async removeGeofence(options) {\n        if (!this.geofenceStore.has(options.identifier)) {\n            throw new Error(`Geofence \"${options.identifier}\" not found`);\n        }\n        this.geofenceStore.delete(options.identifier);\n        this.emitDebug(`[GEOFENCE REMOVE] \"${options.identifier}\" (${this.geofenceStore.size}/${GEOFENCE_MAX_COUNT})`);\n    }\n    async removeAllGeofences() {\n        const count = this.geofenceStore.size;\n        this.geofenceStore.clear();\n        this.emitDebug(`[GEOFENCE REMOVE_ALL] removed ${count}`);\n    }\n    async getGeofences() {\n        return { geofences: Array.from(this.geofenceStore.values()) };\n    }\n    startHeartbeat() {\n        if (!this.config)\n            return;\n        this.heartbeatTimer = setInterval(() => {\n            navigator.geolocation.getCurrentPosition((position) => {\n                const location = this.geolocationToLocation(position);\n                this.notifyListeners('onHeartbeat', { location, timestamp: Date.now() });\n                this.heartbeatCount++;\n                this.emitDebug(`HEARTBEAT #${this.heartbeatCount} with location`);\n            }, (_error) => {\n                // Emit heartbeat with null location to match native platform behavior\n                this.notifyListeners('onHeartbeat', { location: null, timestamp: Date.now() });\n                this.heartbeatCount++;\n                this.emitDebug(`HEARTBEAT #${this.heartbeatCount} no location`);\n            });\n        }, (this.config.heartbeatInterval ?? 15) * 1000);\n    }\n    stopHeartbeat() {\n        if (this.heartbeatTimer !== null) {\n            clearInterval(this.heartbeatTimer);\n            this.heartbeatTimer = null;\n        }\n    }\n    geolocationToLocation(position) {\n        return {\n            latitude: position.coords.latitude,\n            longitude: position.coords.longitude,\n            accuracy: position.coords.accuracy,\n            speed: position.coords.speed ?? 0,\n            heading: position.coords.heading ?? -1,\n            altitude: position.coords.altitude ?? 0,\n            timestamp: position.timestamp,\n            isMoving: (position.coords.speed ?? 0) > 0.5,\n            isMock: false,\n        };\n    }\n    sendHttp(location) {\n        if (!this.httpConfig)\n            return;\n        const headers = {\n            'Content-Type': 'application/json',\n            ...(this.httpConfig.headers ?? {}),\n        };\n        fetch(this.httpConfig.url, {\n            method: 'POST',\n            headers,\n            body: JSON.stringify({ location }),\n        })\n            .then(async (response) => {\n            const responseText = await response.text().catch(() => '');\n            if (response.ok) {\n                this.httpSuccessCount++;\n                this.emitDebug(`HTTP OK #${this.httpSuccessCount} status=${response.status}`);\n            }\n            else {\n                this.httpErrorCount++;\n                this.emitDebug(`HTTP ERROR #${this.httpErrorCount} status=${response.status}`);\n            }\n            this.notifyListeners('onHttp', {\n                statusCode: response.status,\n                success: response.ok,\n                responseText,\n                bufferedCount: 0,\n            });\n        })\n            .catch((error) => {\n            this.httpErrorCount++;\n            this.emitDebug(`HTTP ERROR #${this.httpErrorCount} status=0 error=${error.message}`);\n            this.notifyListeners('onHttp', {\n                statusCode: 0,\n                success: false,\n                responseText: '',\n                error: error.message,\n                bufferedCount: 0,\n            });\n        });\n    }\n    emitDebug(message) {\n        if (!this.debug)\n            return;\n        console.debug(`[BGL_DEBUG] ${message}`);\n        this.notifyListeners('onDebug', { message, timestamp: Date.now() });\n    }\n    resetCounters() {\n        this.locationCount = 0;\n        this.heartbeatCount = 0;\n        this.httpSuccessCount = 0;\n        this.httpErrorCount = 0;\n    }\n}\n//# sourceMappingURL=web.js.map"],"names":["registerPlugin","WebPlugin"],"mappings":"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"}

package/ios/Sources/BGLocationCore/Config/BGLConfigParser.swift

@@ -0,0 +1,88 @@
+import Foundation
+
+/// Parses configuration dictionary into typed config structs.
+/// Framework-agnostic: accepts [String: Any] instead of Capacitor CAPPluginCall.
+/// Bridge adapters provide: `BGLConfigParser.parse(call.options)` (Capacitor)
+/// or `BGLConfigParser.parse(dict)` (React Native / Flutter).
+public enum BGLConfigParser {
+
+    public struct ParsedConfig {
+        public let desiredAccuracy: String
+        public let heartbeatInterval: Int
+        public let distanceFilter: Double
+        public let distanceFilterMode: String
+        public let autoDistanceFilterConfig: AutoDistanceFilterConfig?
+        public let isDebug: Bool
+        public let debugSounds: Bool
+        public let httpUrl: String?
+        public let httpHeaders: [String: String]
+        public let bufferMaxSize: Int?
+    }
+
+    /// Parse all configuration values from a dictionary.
+    public static func parse(_ options: [String: Any]) -> ParsedConfig {
+        let desiredAccuracy = options["desiredAccuracy"] as? String ?? "high"
+        let heartbeatInterval = options["heartbeatInterval"] as? Int ?? 15
+
+        let distanceFilterRaw = options["distanceFilter"]
+        let isAutoMode = (distanceFilterRaw as? String) == "auto"
+        let distanceFilterMode = isAutoMode ? "auto" : "fixed"
+
+        var distanceFilter: Double
+        var autoDistanceFilterConfig: AutoDistanceFilterConfig?
+
+        if isAutoMode {
+            let autoObj = options["autoDistanceFilter"] as? [String: Any]
+            let targetInterval =
+                autoObj?["targetInterval"] as? Double
+                ?? AutoDistanceFilterConfig.defaultTargetInterval
+            let minDistance =
+                autoObj?["minDistance"] as? Double
+                ?? Double(AutoDistanceFilterConfig.defaultMinDistance)
+            let maxDistance =
+                autoObj?["maxDistance"] as? Double
+                ?? Double(AutoDistanceFilterConfig.defaultMaxDistance)
+            let config = AutoDistanceFilterConfig(
+                targetInterval: targetInterval,
+                minDistance: minDistance,
+                maxDistance: maxDistance
+            )
+            autoDistanceFilterConfig = config
+            distanceFilter = config.minDistance
+        } else {
+            autoDistanceFilterConfig = nil
+            distanceFilter = (distanceFilterRaw as? Double) ?? 15.0
+        }
+
+        let isDebug = options["debug"] as? Bool ?? false
+        let debugSounds = options["debugSounds"] as? Bool ?? false
+
+        // HTTP config
+        var httpUrl: String?
+        var httpHeaders: [String: String] = [:]
+        var bufferMaxSize: Int?
+
+        if let httpObj = options["http"] as? [String: Any], let url = httpObj["url"] as? String {
+            httpUrl = url
+            if let headersObj = httpObj["headers"] as? [String: String] {
+                httpHeaders = headersObj
+            }
+            if let bufferObj = httpObj["buffer"] as? [String: Any] {
+                bufferMaxSize = bufferObj["maxSize"] as? Int ?? 1000
+            }
+        }
+
+        return ParsedConfig(
+            desiredAccuracy: desiredAccuracy,
+            heartbeatInterval: heartbeatInterval,
+            distanceFilter: distanceFilter,
+            distanceFilterMode: distanceFilterMode,
+            autoDistanceFilterConfig: autoDistanceFilterConfig,
+            isDebug: isDebug,
+            debugSounds: debugSounds,
+            httpUrl: httpUrl,
+            httpHeaders: httpHeaders,
+            bufferMaxSize: bufferMaxSize
+        )
+    }
+}

package/ios/Sources/BGLocationCore/Config/BGLVersion.swift

@@ -0,0 +1,6 @@
+import Foundation
+
+/// Version constant for the BGLocationCore native library.
+public enum BGLVersion {
+    public static let version = "1.0.2"
+}

package/ios/Sources/BGLocationCore/Debug/BGLDebugLogger.swift

@@ -0,0 +1,201 @@
+import Foundation
+import os.log
+
+#if os(iOS)
+    import AVFoundation
+    import AudioToolbox
+#endif
+
+/// Debug logger for the BackgroundLocation plugin.
+/// Emits structured log messages via os_log and optionally plays system sounds.
+public class BGLDebugLogger {
+
+    /// Callback to emit debug events to the JS layer.
+    public var onDebug: ((String) -> Void)?
+
+    public private(set) var isEnabled = false
+    public private(set) var soundsEnabled = false
+
+    // Counters for debug summary
+    public private(set) var locationCount = 0
+    public private(set) var heartbeatCount = 0
+    public private(set) var httpSuccessCount = 0
+    public private(set) var httpErrorCount = 0
+
+    private let log = OSLog(subsystem: "dev.bglocation", category: "Debug")
+    #if os(iOS)
+        private var audioSessionConfigured = false
+    #endif
+
+    public init() {}
+
+    public func configure(debug: Bool, debugSounds: Bool) {
+        isEnabled = debug
+        soundsEnabled = debugSounds
+        if debug && debugSounds {
+            configureAudioSession()
+        }
+        if debug {
+            emit("Debug mode enabled (sounds: \(debugSounds))")
+        }
+    }
+
+    public func reset() {
+        locationCount = 0
+        heartbeatCount = 0
+        httpSuccessCount = 0
+        httpErrorCount = 0
+    }
+
+    // MARK: - Log Methods
+
+    public func logConfigure(distanceFilter: Double, heartbeat: Int, httpUrl: String?) {
+        guard isEnabled else { return }
+        let http = httpUrl ?? "disabled"
+        emit("CONFIGURE distance=\(distanceFilter)m heartbeat=\(heartbeat)s http=\(http)")
+    }
+
+    public func logStart() {
+        guard isEnabled else { return }
+        reset()
+        emit("START tracking")
+        playSound(.start)
+    }
+
+    public func logStop() {
+        guard isEnabled else { return }
+        emit(
+            "STOP tracking \u{2014} locations=\(locationCount) heartbeats=\(heartbeatCount) http_ok=\(httpSuccessCount) http_err=\(httpErrorCount)"
+        )
+        playSound(.stop)
+    }
+
+    public func logLocation(
+        lat: Double, lng: Double, accuracy: Double, speed: Double, isMoving: Bool
+    ) {
+        guard isEnabled else { return }
+        locationCount += 1
+        let status = isMoving ? "moving" : "stationary"
+        emit(
+            "LOCATION #\(locationCount) (\(String(format: "%.5f", lat)), \(String(format: "%.5f", lng))) acc=\(String(format: "%.1f", accuracy))m spd=\(String(format: "%.1f", speed))m/s \(status)"
+        )
+        playSound(.location)
+    }
+
+    public func logHeartbeat(hasLocation: Bool) {
+        guard isEnabled else { return }
+        heartbeatCount += 1
+        let locStatus = hasLocation ? "with location" : "no location (cold start)"
+        emit("HEARTBEAT #\(heartbeatCount) \(locStatus)")
+        playSound(.heartbeat)
+    }
+
+    public func logHttp(statusCode: Int, success: Bool, error: String?) {
+        guard isEnabled else { return }
+        if success {
+            httpSuccessCount += 1
+            emit("HTTP OK #\(httpSuccessCount) status=\(statusCode)")
+        } else {
+            httpErrorCount += 1
+            let errMsg = error ?? "unknown"
+            emit("HTTP ERROR #\(httpErrorCount) status=\(statusCode) error=\(errMsg)")
+            playSound(.httpError)
+        }
+    }
+
+    public func logPermission(status: String) {
+        guard isEnabled else { return }
+        emit("PERMISSION \(status)")
+    }
+
+    /// Log an arbitrary debug message. Used for one-off events like SLC restart.
+    public func logMessage(_ message: String) {
+        guard isEnabled else { return }
+        emit(message)
+    }
+
+    // MARK: - Geofence Logging
+
+    public func logGeofenceAdd(identifier: String) {
+        guard isEnabled else { return }
+        emit("GEOFENCE ADD \(identifier)")
+        playSound(.geofenceAdd)
+    }
+
+    public func logGeofenceAddBatch(count: Int) {
+        guard isEnabled else { return }
+        emit("GEOFENCE ADD_BATCH count=\(count)")
+        playSound(.geofenceAdd)
+    }
+
+    public func logGeofenceRemove(identifier: String) {
+        guard isEnabled else { return }
+        emit("GEOFENCE REMOVE \(identifier)")
+    }
+
+    public func logGeofenceRemoveAll(count: Int) {
+        guard isEnabled else { return }
+        emit("GEOFENCE REMOVE_ALL count=\(count)")
+    }
+
+    public func logGeofenceEvent(identifier: String, action: String) {
+        guard isEnabled else { return }
+        emit("GEOFENCE \(action.uppercased()) \(identifier)")
+        playSound(.geofenceEvent)
+    }
+
+    // MARK: - Private
+
+    private func emit(_ message: String) {
+        let prefixed = "[BackgroundLocation] \(message)"
+        os_log("%{public}@", log: log, type: .debug, prefixed)
+        onDebug?(message)
+    }
+
+    // MARK: - Sounds
+
+    enum SoundEvent {
+        case start, stop, location, heartbeat, httpError, geofenceAdd, geofenceEvent
+    }
+
+    #if os(iOS)
+        private func configureAudioSession() {
+            guard !audioSessionConfigured else { return }
+            do {
+                let session = AVAudioSession.sharedInstance()
+                try session.setCategory(.playback, options: .mixWithOthers)
+                try session.setActive(true)
+                audioSessionConfigured = true
+            } catch {
+                os_log(
+                    "Audio session setup failed: %{public}@", log: log, type: .error,
+                    error.localizedDescription)
+            }
+        }
+
+        private func playSound(_ event: SoundEvent) {
+            guard isEnabled, soundsEnabled else { return }
+            let soundId: SystemSoundID
+            switch event {
+            case .start:
+                soundId = 1054  // begin recording
+            case .stop:
+                soundId = 1055  // end recording
+            case .location:
+                soundId = 1052  // tink (louder — location is the primary event)
+            case .heartbeat:
+                soundId = 1057  // tock (quieter — heartbeat is a status ping)
+            case .httpError:
+                soundId = 1073  // sms alert
+            case .geofenceAdd:
+                soundId = 1116  // key press click
+            case .geofenceEvent:
+                soundId = 1117  // key press delete
+            }
+            AudioServicesPlayAlertSoundWithCompletion(soundId, nil)
+        }
+    #else
+        private func configureAudioSession() {}
+        private func playSound(_ event: SoundEvent) {}
+    #endif
+}