@transistorsoft/background-geolocation-types 5.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Transistor Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# @transistorsoft/background-geolocation-types
+
+Shared **TypeScript type definitions** and **generated API documentation** for Transistor Software’s Background Geolocation SDKs:
+
+- **React Native**
+- **Capacitor**
+- **Cordova**
+
+This package centralizes all public TypeScript interfaces, enums, utility types, and TypeDoc‑generated documentation shared across platform SDKs.  
+It contains **types only** — no runtime code.
+
+---
+
+## 📦 Installation
+
+Install as a development dependency:
+
+```bash
+npm install @transistorsoft/background-geolocation-types --save-dev
+```
+
+```bash
+yarn add -D @transistorsoft/background-geolocation-types
+```
+
+```bash
+pnpm add -D @transistorsoft/background-geolocation-types
+```
+
+---
+
+## 🎯 Purpose
+
+This package exists to:
+
+1. Provide **strict, shared TypeScript types** across all Background Geolocation SDKs.
+2. Serve as the source for **Typedoc documentation**.
+3. Ensure consistent API signatures across React Native, Capacitor, and Cordova.
+
+This avoids duplication and keeps all platform SDKs perfectly in sync.
+
+---
+
+## 📘 Using the Types
+
+Typically, consuming SDKs re‑export all public types:
+
+```ts
+import BackgroundGeolocation, {
+  Config,
+  GeoConfig,
+  HttpConfig,
+  PersistMode,
+  Location,
+  State
+} from '{{pluginName}}';
+```
+
+If desired, types can also be imported directly:
+
+```ts
+import type { Location, GeofenceEvent, PersistMode } 
+  from '@transistorsoft/background-geolocation-types';
+```
+
+---
+
+## 📚 Documentation
+
+Generate API docs using:
+
+```bash
+pnpm run docs
+```
+
+This runs TypeDoc with the custom Transistorsoft plugins:
+
+- **typedoc-plugin-templates**
+- **typedoc-plugin-gitlink**
+- **typedoc-plugin-mediaplayer**
+- **typedoc-plugin-site**
+
+Docs output to:
+
+```
+./docs
+```
+
+---
+
+## 🛠️ Development
+
+Build the project:
+
+```bash
+pnpm run clean && pnpm run build
+```
+
+Watch mode:
+
+```bash
+pnpm run watch
+```
+
+---
+
+## 📁 Structure
+
+```
+background-geolocation-types/
+  ├── src/
+  ├── dist/
+  ├── docs/
+  ├── tools/
+  ├── typedoc.json
+  └── tsconfig.json
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome — especially improvements to TypeScript typings and documentation.
+
+Please ensure:
+
+- No runtime logic is added — this package is **types only**.
+- Definitions remain platform‑agnostic.
+- Changes reflect the APIs of all supported SDKs.
+
+---
+
+## 📄 License
+
+Commercial license. See `LICENSE` for details.
+
+

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

@@ -0,0 +1,6 @@
+/**
+ * Main SDK API used by consumers.
+ * @category Primary API
+ */
+export interface BackgroundGeolocation extends BackgroundGeolocationAPI {
+}

package/dist/core/api/BackgroundGeolocation.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,44 @@
+/**
+ * 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/CurrentPositionRequest.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,77 @@
+/**
+ * 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>;
+}

package/dist/core/api/DeviceSettings.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });