@tauri-apps/plugin-geolocation 2.0.0-rc.0

package/LICENSE.spdx

@@ -0,0 +1,20 @@
+SPDXVersion: SPDX-2.1
+DataLicense: CC0-1.0
+PackageName: tauri
+DataFormat: SPDXRef-1
+PackageSupplier: Organization: The Tauri Programme in the Commons Conservancy
+PackageHomePage: https://tauri.app
+PackageLicenseDeclared: Apache-2.0
+PackageLicenseDeclared: MIT
+PackageCopyrightText: 2019-2022, The Tauri Programme in the Commons Conservancy
+PackageSummary: <text>Tauri is a rust project that enables developers to make secure
+and small desktop applications using a web frontend.
+                </text>
+PackageComment: <text>The package includes the following libraries; see
+Relationship information.
+                </text>
+Created: 2019-05-20T09:00:00Z
+PackageDownloadLocation: git://github.com/tauri-apps/tauri
+PackageDownloadLocation: git+https://github.com/tauri-apps/tauri.git
+PackageDownloadLocation: git+ssh://github.com/tauri-apps/tauri.git
+Creator: Person: Daniel Thompson-Yvetot

package/README.md

@@ -0,0 +1,145 @@
+![geolocation](https://github.com/tauri-apps/plugins-workspace/raw/v2/plugins/geolocation/banner.png)
+
+This plugin provides APIs for getting and tracking the device's current position, including information about altitude, heading, and speed (if available).
+
+## Install
+
+_This plugin requires a Rust version of at least **1.75**_
+
+There are three general methods of installation that we can recommend.
+
+1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked)
+2. Pull sources directly from Github using git tags / revision hashes (most secure)
+3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use)
+
+Install the Core plugin by adding the following to your `Cargo.toml` file:
+
+`src-tauri/Cargo.toml`
+
+```toml
+[dependencies]
+tauri-plugin-geolocation = "2.0.0-rc"
+# alternatively with Git:
+tauri-plugin-geolocation = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" }
+```
+
+You can install the JavaScript Guest bindings using your preferred JavaScript package manager:
+
+> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use.
+
+<!-- Add the branch for installations using git! -->
+
+```sh
+pnpm add @tauri-apps/plugin-geolocation
+# or
+npm add @tauri-apps/plugin-geolocation
+# or
+yarn add @tauri-apps/plugin-geolocation
+
+# alternatively with Git:
+pnpm add https://github.com/tauri-apps/tauri-plugin-geolocation#v2
+# or
+npm add https://github.com/tauri-apps/tauri-plugin-geolocation#v2
+# or
+yarn add https://github.com/tauri-apps/tauri-plugin-geolocation#v2
+```
+
+## Setting up
+
+### iOS
+
+Apple requires privacy descriptions to be specified in `Info.plist` for location information:
+
+- `NSLocationWhenInUseDescription`
+
+### Android
+
+This plugin automatically adds the following permissions to your `AndroidManifest.xml` file:
+
+```xml
+<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+```
+
+If your app requires GPS functionality to function, **you** should add the following to your `AndroidManifest.xml` file:
+
+```xml
+<uses-feature android:name="android.hardware.gps" android:required="true" />
+```
+
+The Google Play Store uses this property to decide whether it should show the app to devices without GPS capabilities.
+
+## Usage
+
+First you need to register the core plugin with Tauri:
+
+`src-tauri/src/main.rs`
+
+```rust
+fn main() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_geolocation::init())
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+Afterwards all the plugin's APIs are available through the JavaScript guest bindings:
+
+```javascript
+import { getCurrentPosition, watchPosition } from "@tauri-apps/plugin-log";
+
+const pos = await getCurrentPosition();
+
+await watchPosition(
+  { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 },
+  (pos) => {
+    console.log(pos);
+  }
+);
+```
+
+## Contributing
+
+PRs accepted. Please make sure to read the Contributing Guide before making a pull request.
+
+## Contributed By
+
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="middle">
+        <a href="https://crabnebula.dev" target="_blank">
+          <img src="contributors/crabnebula.svg" alt="CrabNebula" width="283">
+        </a>
+      </td>
+      <td align="center" valign="middle">
+        <a href="https://rescue.co" target="_blank">
+            <img src="contributors/rescue.png" alt="Rescue.co" width="283" height="90">
+        </a>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+## Partners
+
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="middle">
+        <a href="https://crabnebula.dev" target="_blank">
+          <img src="https://github.com/tauri-apps/plugins-workspace/raw/v2/.github/sponsors/crabnebula.svg" alt="CrabNebula" width="283">
+        </a>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+For the complete list of sponsors please visit our [website](https://tauri.app#sponsors) and [Open Collective](https://opencollective.com/tauri).
+
+## License
+
+Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy.
+
+MIT or MIT/Apache 2.0 where applicable.

package/dist-js/bindings.d.ts

@@ -0,0 +1,113 @@
+/** user-defined commands **/
+export declare const commands: {
+    getCurrentPosition(options: PositionOptions | null): Promise<Result<Position, Error>>;
+    watchPosition(options: PositionOptions, channel: any): Promise<Result<null, Error>>;
+    clearWatch(channelId: number): Promise<Result<null, Error>>;
+    checkPermissions(): Promise<Result<PermissionStatus, Error>>;
+    requestPermissions(permissions: PermissionType[] | null): Promise<Result<PermissionStatus, Error>>;
+};
+/** user-defined events **/
+/** user-defined statics **/
+/** user-defined types **/
+export type Coordinates = {
+    /**
+     * Latitude in decimal degrees.
+     */
+    latitude: number;
+    /**
+     * Longitude in decimal degrees.
+     */
+    longitude: number;
+    /**
+     * Accuracy level of the latitude and longitude coordinates in meters.
+     */
+    accuracy: number;
+    /**
+     * Accuracy level of the altitude coordinate in meters, if available.
+     * Available on all iOS versions and on Android 8 and above.
+     */
+    altitudeAccuracy: number | null;
+    /**
+     * The altitude the user is at, if available.
+     */
+    altitude: number | null;
+    speed: number | null;
+    /**
+     * The heading the user is facing, if available.
+     */
+    heading: number | null;
+};
+export type Error = never;
+/**
+ * Permission state.
+ */
+export type PermissionState = 
+/**
+ * Permission access has been granted.
+ */
+"granted"
+/**
+ * Permission access has been denied.
+ */
+ | "denied"
+/**
+ * The end user should be prompted for permission.
+ */
+ | "prompt";
+export type PermissionStatus = {
+    /**
+     * Permission state for the location alias.
+     *
+     * On Android it requests/checks both ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions.
+     *
+     * On iOS it requests/checks location permissions.
+     */
+    location: PermissionState;
+    /**
+     * Permissions state for the coarseLoaction alias.
+     *
+     * On Android it requests/checks ACCESS_COARSE_LOCATION.
+     *
+     * On Android 12+, users can choose between Approximate location (ACCESS_COARSE_LOCATION) and Precise location (ACCESS_FINE_LOCATION).
+     *
+     * On iOS it will have the same value as the `location` alias.
+     */
+    coarseLocation: PermissionState;
+};
+export type PermissionType = "location" | "coarseLocation";
+export type Position = {
+    /**
+     * Creation time for these coordinates.
+     */
+    timestamp: number;
+    /**
+     * The GPD coordinates along with the accuracy of the data.
+     */
+    coords: Coordinates;
+};
+export type PositionOptions = {
+    /**
+     * High accuracy mode (such as GPS, if available)
+     * Will be ignored on Android 12+ if users didn't grant the ACCESS_FINE_LOCATION permission.
+     */
+    enableHighAccuracy: boolean;
+    /**
+     * The maximum wait time in milliseconds for location updates.
+     * On Android the timeout gets ignored for getCurrentPosition.
+     * Ignored on iOS
+     */
+    timeout: number;
+    /**
+     * The maximum age in milliseconds of a possible cached position that is acceptable to return.
+     * Default: 0
+     * Ignored on iOS
+     */
+    maximumAge: number;
+};
+export type Result<T, E> = {
+    status: "ok";
+    data: T;
+} | {
+    status: "error";
+    error: E;
+};

package/dist-js/index.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+var core = require('@tauri-apps/api/core');
+require('@tauri-apps/api/event');
+
+// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+// @ts-nocheck
+// This file was generated by [tauri-specta](https://github.com/oscartbeaumont/tauri-specta). Do not edit this file manually.
+/** user-defined commands **/
+const commands = {
+    async getCurrentPosition(options) {
+        try {
+            return {
+                status: "ok",
+                data: await core.invoke("plugin:geolocation|get_current_position", {
+                    options,
+                }),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+    async watchPosition(options, channel) {
+        try {
+            return {
+                status: "ok",
+                data: await core.invoke("plugin:geolocation|watch_position", {
+                    options,
+                    channel,
+                }),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+    async clearWatch(channelId) {
+        try {
+            return {
+                status: "ok",
+                data: await core.invoke("plugin:geolocation|clear_watch", {
+                    channelId,
+                }),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+    async checkPermissions() {
+        try {
+            return {
+                status: "ok",
+                data: await core.invoke("plugin:geolocation|check_permissions"),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+    async requestPermissions(permissions) {
+        try {
+            return {
+                status: "ok",
+                data: await core.invoke("plugin:geolocation|request_permissions", {
+                    permissions,
+                }),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+};
+
+// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+/* eslint-disable @typescript-eslint/unbound-method */
+async function watchPosition(options, 
+// TODO: This can receive errors too
+cb) {
+    const channel = new core.Channel();
+    channel.onmessage = cb;
+    await commands.watchPosition(options, channel);
+    return channel.id;
+}
+const { getCurrentPosition, clearWatch, checkPermissions, requestPermissions, } = commands;
+// export { events };
+
+exports.checkPermissions = checkPermissions;
+exports.clearWatch = clearWatch;
+exports.getCurrentPosition = getCurrentPosition;
+exports.requestPermissions = requestPermissions;
+exports.watchPosition = watchPosition;

package/dist-js/index.d.ts

@@ -0,0 +1,4 @@
+import { type PositionOptions, type Position } from "./bindings";
+export declare function watchPosition(options: PositionOptions, cb: (location: Position | string) => void): Promise<number>;
+export declare const getCurrentPosition: (options: PositionOptions | null) => Promise<import("./bindings").Result<Position, import("./bindings").Error>>, clearWatch: (channelId: number) => Promise<import("./bindings").Result<null, import("./bindings").Error>>, checkPermissions: () => Promise<import("./bindings").Result<import("./bindings").PermissionStatus, import("./bindings").Error>>, requestPermissions: (permissions: import("./bindings").PermissionType[] | null) => Promise<import("./bindings").Result<import("./bindings").PermissionStatus, import("./bindings").Error>>;
+export type { PermissionState, PermissionStatus, PermissionType, Position, PositionOptions, Coordinates, } from "./bindings";

package/dist-js/index.js

@@ -0,0 +1,107 @@
+import { invoke, Channel } from '@tauri-apps/api/core';
+import '@tauri-apps/api/event';
+
+// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+// @ts-nocheck
+// This file was generated by [tauri-specta](https://github.com/oscartbeaumont/tauri-specta). Do not edit this file manually.
+/** user-defined commands **/
+const commands = {
+    async getCurrentPosition(options) {
+        try {
+            return {
+                status: "ok",
+                data: await invoke("plugin:geolocation|get_current_position", {
+                    options,
+                }),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+    async watchPosition(options, channel) {
+        try {
+            return {
+                status: "ok",
+                data: await invoke("plugin:geolocation|watch_position", {
+                    options,
+                    channel,
+                }),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+    async clearWatch(channelId) {
+        try {
+            return {
+                status: "ok",
+                data: await invoke("plugin:geolocation|clear_watch", {
+                    channelId,
+                }),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+    async checkPermissions() {
+        try {
+            return {
+                status: "ok",
+                data: await invoke("plugin:geolocation|check_permissions"),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+    async requestPermissions(permissions) {
+        try {
+            return {
+                status: "ok",
+                data: await invoke("plugin:geolocation|request_permissions", {
+                    permissions,
+                }),
+            };
+        }
+        catch (e) {
+            if (e instanceof Error)
+                throw e;
+            else
+                return { status: "error", error: e };
+        }
+    },
+};
+
+// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+/* eslint-disable @typescript-eslint/unbound-method */
+async function watchPosition(options, 
+// TODO: This can receive errors too
+cb) {
+    const channel = new Channel();
+    channel.onmessage = cb;
+    await commands.watchPosition(options, channel);
+    return channel.id;
+}
+const { getCurrentPosition, clearWatch, checkPermissions, requestPermissions, } = commands;
+// export { events };
+
+export { checkPermissions, clearWatch, getCurrentPosition, requestPermissions, watchPosition };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@tauri-apps/plugin-geolocation",
+  "version": "2.0.0-rc.0",
+  "license": "MIT or APACHE-2.0",
+  "authors": [
+    "Tauri Programme within The Commons Conservancy"
+  ],
+  "repository": "https://github.com/tauri-apps/plugins-workspace",
+  "type": "module",
+  "types": "./dist-js/index.d.ts",
+  "main": "./dist-js/index.cjs",
+  "module": "./dist-js/index.js",
+  "exports": {
+    "types": "./dist-js/index.d.ts",
+    "import": "./dist-js/index.js",
+    "require": "./dist-js/index.cjs"
+  },
+  "scripts": {
+    "build": "rollup -c"
+  },
+  "files": [
+    "dist-js",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@tauri-apps/api": "^2.0.0-rc.0"
+  }
+}