@bglocation/capacitor 1.1.0

package/CapacitorBackgroundLocation.podspec

@@ -0,0 +1,19 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(File.dirname(__FILE__), 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name         = 'CapacitorBackgroundLocation'
+  s.version      = package['version']
+  s.summary      = 'Capacitor plugin for continuous background location tracking'
+  s.license      = { :type => 'Proprietary', :text => 'UNLICENSED — all rights reserved' }
+  s.homepage     = 'https://bglocation.dev'
+  s.author       = 'Szymon Walczak'
+  s.source       = { :git => 'https://gitlab.com/szymonwalczak/capacitor-background-location.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m}'
+
+  s.ios.deployment_target = '15.0'
+
+  s.dependency 'Capacitor'
+  s.swift_version = '5.0'
+end

package/LICENSE.md

@@ -0,0 +1,97 @@
+Elastic License 2.0 (ELv2)
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
+
+---
+
+Copyright (c) 2025-2026 Szymon Walczak. All rights reserved.

package/Package.swift

@@ -0,0 +1,44 @@
+// swift-tools-version: 5.9
+
+// SPM package for Capacitor 8 plugin integration and unit testing.
+// BGLocationCore Swift sources are vendored in ios/Sources/BGLocationCore/
+// (no remote fetch or binary framework needed).
+
+import PackageDescription
+
+let package = Package(
+    name: "CapacitorBglocation",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "CapacitorBglocation",
+            targets: ["BackgroundLocationPlugin"]
+        )
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
+    ],
+    targets: [
+        .target(
+            name: "BGLocationCore",
+            path: "ios/Sources/BGLocationCore"
+        ),
+        .target(
+            name: "BackgroundLocationPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+                "BGLocationCore",
+            ],
+            path: "ios/Sources/BackgroundLocationPlugin"
+        ),
+        .testTarget(
+            name: "BglocationCoreTests",
+            dependencies: [
+                "BackgroundLocationPlugin",
+                "BGLocationCore",
+            ],
+            path: "ios/Tests"
+        ),
+    ]
+)

package/README.md

@@ -0,0 +1,264 @@
+# @bglocation/capacitor
+
+Capacitor 8 plugin for continuous background location tracking on iOS and Android with optional native HTTP POST.
+
+> **Status**: POC (Proof of Concept)
+
+## Features
+
+- Continuous GPS tracking in background (iOS + Android)
+- Configurable `distanceFilter`, `desiredAccuracy`, update intervals
+- **Adaptive distance filter** — `distanceFilter: 'auto'` dynamically adjusts based on speed (EMA smoothing) to maintain ~10s update interval
+- Heartbeat timer — periodic event even when stationary
+- Native HTTP POST — send location to backend from native layer
+- **Offline buffer** — SQLite-backed queue for failed HTTP requests with automatic retry
+- **Configurable notification** — custom title and text for Android foreground service notification (i18n ready)
+- **Debug mode** — verbose logs, `onDebug` events, optional system sounds, dynamic Android notification with GPS counters
+- **OEM battery killer detection** — warns when battery optimization may kill tracking (Android), with dontkillmyapp.com links
+- **Approximate location warning** — detects and warns when user granted only approximate location (iOS 14+)
+- **Significant Location Change fallback** — SLC watchdog auto-restarts GPS after iOS kills the app (iOS)
+- **Mock location detection** — detects mock/test location providers (Android)
+- **Permission rationale** — emits event before requesting background location on Android 11+ for custom rationale UI
+- **Geofencing** — monitor enter/exit/dwell for up to 20 circular regions (iOS + Android), with persistence across app restarts
+- Events: `onLocation`, `onHeartbeat`, `onHttp`, `onProviderChange`, `onDebug`, `onBatteryWarning`, `onAccuracyWarning`, `onMockLocation`, `onPermissionRationale`, `onTrialExpired`, `onGeofence`
+- Web fallback for development/testing in browser
+- 774 unit tests across 3 platforms
+
+## Documentation
+
+Detailed documentation is in the [`.wiki/`](.wiki/README.md) directory:
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](.wiki/Architecture.md) | System architecture, data flow, platform differences |
+| [API Reference](.wiki/API.md) | Full API: methods, events, interfaces, error codes |
+| [iOS](.wiki/iOS.md) | CLLocationManager, permissions, heartbeat, background modes |
+| [Android](.wiki/Android.md) | Foreground Service, FusedLocation, permissions, binding |
+| [Web](.wiki/Web.md) | Browser fallback implementation |
+| [HTTP](.wiki/HTTP.md) | Native HTTP sender: config, format, timeouts, errors |
+| [Testing](.wiki/Testing.md) | Test strategy, running tests, CI integration |
+| [Geofencing](.wiki/Geofencing.md) | Geofence API, dwell, persistence, platform differences |
+| [Deployment](.wiki/Deployment.md) | Production checklist: license key, platform requirements, troubleshooting |
+| [Known Limitations](.wiki/Known-Limitations.md) | POC limitations and production roadmap |
+
+## Platforms
+
+| Platform | Min Version | Implementation |
+|----------|-------------|----------------|
+| iOS      | 15.0        | `CLLocationManager` with background modes |
+| Android  | API 26      | `FusedLocationProviderClient` + Foreground Service |
+| Web      | —           | `navigator.geolocation` (dev/testing fallback) |
+
+## Installation
+
+```bash
+npm install @bglocation/capacitor
+npx cap sync
+```
+
+### iOS
+
+Add **all** of the following keys to `Info.plist`:
+
+```xml
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>We need your location to track the tour route</string>
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>We need your location to show your position on the map</string>
+<key>UIBackgroundModes</key>
+<array>
+  <string>location</string>
+</array>
+```
+
+> **Important**: Both `NSLocationAlwaysAndWhenInUseUsageDescription` and `NSLocationWhenInUseUsageDescription` are required. Missing either will cause a runtime crash with a privacy violation. The plugin calls `requestAlwaysAuthorization()` automatically when tracking starts if the user hasn't been prompted yet.
+>
+> `allowsBackgroundLocationUpdates = true` is set internally by the plugin during `configure()`, **before** the app enters background — this is required by iOS.
+
+### Android
+
+Permissions are declared in the plugin's `AndroidManifest.xml` and merged automatically:
+- `ACCESS_FINE_LOCATION`
+- `ACCESS_COARSE_LOCATION`
+- `ACCESS_BACKGROUND_LOCATION` (Android 10+)
+- `FOREGROUND_SERVICE` / `FOREGROUND_SERVICE_LOCATION`
+
+**Your app must request permissions before calling `start()`**. The plugin only *checks* permissions — it does not prompt the user. On Android 10+ (API 29), the user must explicitly grant "Allow all the time" for background location to work. If permissions are not granted, `start()` will reject with an error.
+
+> **iOS vs Android difference**: iOS auto-prompts for `Always` authorization via `requestAlwaysAuthorization()`. Android requires the app to handle permission requests explicitly.
+
+## Quick Start
+
+```typescript
+import { BackgroundLocation } from '@bglocation/capacitor';
+
+// 1. Request permissions
+const perms = await BackgroundLocation.checkPermissions();
+if (perms.location !== 'granted') {
+  await BackgroundLocation.requestPermissions({ permissions: ['location'] });
+}
+if (perms.backgroundLocation !== 'granted') {
+  await BackgroundLocation.requestPermissions({ permissions: ['backgroundLocation'] });
+}
+
+// 2. Configure
+await BackgroundLocation.configure({
+  distanceFilter: 15,                  // meters
+  desiredAccuracy: 'high',             // 'high' | 'balanced' | 'low'
+  locationUpdateInterval: 5000,        // ms (Android only)
+  fastestLocationUpdateInterval: 2000, // ms (Android only)
+  heartbeatInterval: 15,               // seconds
+  http: {                              // optional — native HTTP POST
+    url: 'https://api.example.com/location',
+    headers: { Authorization: 'Bearer <token>' },
+    buffer: { maxSize: 1000 },         // optional — offline buffer for failed requests
+  },
+  notification: {                      // optional — Android foreground service notification
+    title: 'Tour Active',
+    text: 'Tracking your position',
+  },
+  debug: true,                         // optional — verbose logging + onDebug events
+  debugSounds: true,                   // optional — system sounds on events (requires debug: true)
+});
+
+// 3. Listen for events
+BackgroundLocation.addListener('onLocation', (location) => {
+  console.log('Location:', location.latitude, location.longitude);
+});
+
+BackgroundLocation.addListener('onHeartbeat', (event) => {
+  console.log('Heartbeat:', event.location);
+});
+
+BackgroundLocation.addListener('onHttp', (event) => {
+  console.log('HTTP:', event.success, event.statusCode, 'buffered:', event.bufferedCount);
+});
+
+BackgroundLocation.addListener('onDebug', (event) => {
+  console.log('Debug:', event.message);
+});
+
+// 4. Start tracking
+await BackgroundLocation.start();
+
+// ... later ...
+
+// 5. Stop tracking
+await BackgroundLocation.stop();
+await BackgroundLocation.removeAllListeners();
+```
+
+## API Overview
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `checkPermissions()` | `LocationPermissionStatus` | Check current permission state |
+| `requestPermissions(options?)` | `LocationPermissionStatus` | Request location permissions |
+| `configure(options)` | `ConfigureResult` | Set tracking parameters (call before `start()`). Supports partial reconfiguration — omitted fields are merged with previous config. |
+| `start()` | `LocationState` | Start background tracking |
+| `stop()` | `LocationState` | Stop tracking |
+| `getState()` | `LocationState` | Get current plugin state |
+| `getCurrentPosition(options?)` | `Location` | One-shot position fix |
+| `checkBatteryOptimization()` | `BatteryWarningEvent` | Check OEM battery optimization state (Android) |
+| `requestBatteryOptimization()` | `BatteryWarningEvent` | Open battery optimization settings (Android) |
+| `addGeofence(options)` | `void` | Add a geofence (max 20) |
+| `addGeofences(options)` | `void` | Add multiple geofences atomically |
+| `removeGeofence(options)` | `void` | Remove a geofence by identifier |
+| `removeAllGeofences()` | `void` | Remove all geofences |
+| `getGeofences()` | `{ geofences: Geofence[] }` | Get registered geofences |
+| `removeAllListeners()` | `void` | Remove all listeners and stop tracking |
+
+### Events
+
+| Event | Payload | Trigger |
+|-------|---------|---------|
+| `onLocation` | `Location` | Each GPS update (per `distanceFilter`) |
+| `onHeartbeat` | `HeartbeatEvent` | Every `heartbeatInterval` seconds |
+| `onHttp` | `HttpEvent` | After each native HTTP POST response (includes `bufferedCount`) |
+| `onProviderChange` | `ProviderChangeEvent` | GPS/permission status change |
+| `onDebug` | `DebugEvent` | Debug log message (when `debug: true`) |
+| `onBatteryWarning` | `BatteryWarningEvent` | Battery optimization may kill tracking (Android only) |
+| `onAccuracyWarning` | `AccuracyWarningEvent` | Approximate location granted (iOS only) |
+| `onMockLocation` | `MockLocationEvent` | Mock location detected — once per session (Android only) |
+| `onPermissionRationale` | `PermissionRationaleEvent` | Before requesting background location (Android 11+ only) |
+| `onGeofence` | `GeofenceEvent` | Geofence enter/exit/dwell transition |
+
+Full API documentation: [`.wiki/API.md`](.wiki/API.md)
+
+## Licensing
+
+The plugin uses an offline RSA-2048-SHA256 license system with a **perpetual + update gating** model:
+
+- **Full mode**: No restrictions. Requires a valid license key with active updates.
+- **Trial mode**: `debug=true` forced, 30 min tracking limit, 1 h cooldown.
+
+### Update Gating
+
+Each plugin build embeds a build timestamp. If the license's update period (`exp`) has ended before the build date, the plugin runs in trial mode:
+
+```
+License exp = 2027-03-16 (1 year from purchase)
+
+Plugin v1.2 (built 2026-05) → exp > build → FULL ✅ forever
+Plugin v2.0 (built 2027-06) → exp < build → TRIAL ⚠️ renewal needed
+```
+
+### License Renewal
+
+1. Sign in to the [License Portal](https://bglocation.dev/portal)
+2. Expired licenses show a red **Expired** badge
+3. Click **Renew** to generate a new key with a fresh 1-year update period
+4. Update `capacitor.config.ts` with the new key
+
+See [`.wiki/Licensing.md`](.wiki/Licensing.md) for full details.
+
+## Testing
+
+```bash
+npm test              # Web (Vitest) — 164 tests
+npm run test:android  # Android (JUnit + MockK) — 343 tests
+npm run test:ios      # iOS (XCTest via SPM) — 267 tests
+```
+
+Total: **774 tests** across 3 platforms (+ 116 in test app = **890 total**).
+
+See [`.wiki/Testing.md`](.wiki/Testing.md) for details.
+
+## Development
+
+```bash
+npm run build          # TypeScript → dist/
+npm run test:watch     # Vitest watch mode
+npm run verify         # Build + test both native platforms
+npm run verify:ios     # Pod install + xcodebuild
+npm run verify:android # Gradle clean build test
+```
+
+## Debug Sounds
+
+When `debug: true` and `debugSounds: true`, the plugin plays system sounds on key events:
+
+| Event | iOS | Android |
+|-------|-----|---------|
+| **Start tracking** | Begin Recording (1054) | `TONE_PROP_BEEP` |
+| **Stop tracking** | End Recording (1055) | `TONE_PROP_BEEP2` |
+| **Location fix** | Tink (1052) | `TONE_PROP_ACK` |
+| **Heartbeat** | Tock (1057) | `TONE_SUP_CONFIRM` |
+| **HTTP error** | SMS Alert (1073) | `TONE_SUP_ERROR` |
+| **HTTP success** | — (silent) | — (silent) |
+| **Geofence add** | Key Press Click (1116) | `TONE_PROP_ACK` |
+| **Geofence event** | Key Press Delete (1117) | `TONE_SUP_CONFIRM` |
+
+> Web platform does not play sounds — debug events are available via `onDebug` listener and `console.debug`.
+
+## Known Limitations
+
+- No motion/activity detection
+
+See [`.wiki/Known-Limitations.md`](.wiki/Known-Limitations.md) for full list and production roadmap.
+
+## License
+
+ELv2 — all rights reserved.

package/android/build.gradle

@@ -0,0 +1,74 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    playServicesLocationVersion = project.hasProperty('playServicesLocationVersion') ? rootProject.ext.playServicesLocationVersion : '21.0.1'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.21'
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace "dev.bglocation"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+
+    defaultConfig {
+        minSdk project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 26
+        targetSdk project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        buildConfigField "long", "PLUGIN_BUILD_EPOCH", "${(long)(System.currentTimeMillis() / 1000)}L"
+    }
+
+    buildFeatures {
+        buildConfig true
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+
+    kotlinOptions {
+        jvmTarget = '21'
+    }
+
+    testOptions {
+        unitTests.returnDefaultValues = true
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "com.google.android.gms:play-services-location:$playServicesLocationVersion"
+
+    testImplementation "junit:junit:$junitVersion"
+    testImplementation "io.mockk:mockk:1.13.16"
+    testImplementation "org.json:json:20231013"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+
+    <application>
+        <service
+            android:name="dev.bglocation.core.location.BGLLocationForegroundService"
+            android:foregroundServiceType="location"
+            android:exported="false" />
+
+        <receiver
+            android:name="dev.bglocation.core.geofence.BGLGeofenceBroadcastReceiver"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="dev.bglocation.ACTION_GEOFENCE_EVENT" />
+            </intent-filter>
+        </receiver>
+
+        <receiver
+            android:name="dev.bglocation.core.boot.BGLBootCompletedReceiver"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.BOOT_COMPLETED" />
+            </intent-filter>
+        </receiver>
+    </application>
+
+</manifest>