@tokamakdev/plugin-location 0.1.0-beta.102 → 0.1.0-beta.104

package/src/index.ts

@@ -1,37 +1,44 @@
 import { Plugin } from "@tokamakdev/plugin";
 import * as web from "../web/index.js";
+import { nonEmptyText } from "./checks.js";
+import { monitoredRegion, validatePermissionRequest, validateSetup, validateUpdateOptions } from "./options.js";
+import type {
+  ErrorListener,
+  Listener,
+  LocationErrorEvent,
+  LocationPermission,
+  LocationUpdate,
+  MonitoredRegion,
+  PermissionRequest,
+  Position,
+  PositionCallback,
+  PositionErrorCallback,
+  PositionOptions,
+  Region,
+  RegionTransition,
+  SetupConfig,
+  UpdateOptions,
+  Visit,
+} from "./types.js";
 
-export interface Coordinates {
-  readonly latitude: number;
-  readonly longitude: number;
-  readonly accuracy: number;
-  readonly altitude: number | null;
-  readonly altitudeAccuracy: number | null;
-  readonly heading: number | null;
-  readonly speed: number | null;
-}
-
-export interface Position {
-  readonly coords: Coordinates;
-  readonly timestamp: number;
-}
-
-/** Options for `getCurrentPosition`, as the Geolocation API reads them. */
-export interface PositionOptions {
-  /** The age in milliseconds of a recent position to accept instead of a new one; 0 by default. */
-  readonly maximumAge?: number;
-  /** Milliseconds to wait for a position before rejecting with `TimeoutError`; unlimited by default. */
-  readonly timeout?: number;
-}
-
-export type PositionCallback = (position: Position) => void;
-export type PositionErrorCallback = (error: DOMException) => void;
+export type * from "./types.js";
 
 class Location extends Plugin {
   constructor() {
     super("location");
   }
 
+  /**
+   * Applies long-term location awareness, replacing the previous configuration, which the plugin keeps
+   * and applies again at each start. Rejects with `TypeError`, changing nothing, when a value is
+   * invalid, and on Apple platforms with `NotSupportedError` where the device cannot monitor
+   * significant changes.
+   */
+  async setup(config: SetupConfig): Promise<void> {
+    validateSetup(config, "config");
+    return this.hasNativeTransport ? this.call("setup", config) : web.unsupported();
+  }
+
   getCurrentPosition(options: PositionOptions = {}): Promise<Position> {
     if (!this.hasNativeTransport) return web.getCurrentPosition(options);
     return this.call("getCurrentPosition", {
@@ -44,6 +51,98 @@ class Location extends Plugin {
     if (!this.hasNativeTransport) return web.watchPosition(next, error);
     return this.listen("watchPosition", next, error);
   }
+
+  /** The app's in-use and background permission, and the precision it gets. Never asks. */
+  permission(): Promise<LocationPermission> {
+    return this.hasNativeTransport ? this.call("permission") : web.permission();
+  }
+
+  /**
+   * Asks for in-use permission, and for what `options` names, where the user has not answered.
+   * Android asks for background permission once in-use permission is granted. Rejects with
+   * `NeedsUIError` when a prompt would show off screen.
+   */
+  async requestPermission(options: PermissionRequest = {}): Promise<LocationPermission> {
+    validatePermissionRequest(options, "options");
+    return this.hasNativeTransport ? this.call("requestPermission", options) : web.unsupported();
+  }
+
+  /** Whether location services are on for the device. While they are off, nothing locates. */
+  servicesEnabled(): Promise<boolean> {
+    return this.hasNativeTransport ? this.call("servicesEnabled") : web.unsupported();
+  }
+
+  /** Opens the app's page in the system settings, where the user changes its location permission. */
+  openSettings(): Promise<void> {
+    return this.hasNativeTransport ? this.call("openSettings") : web.unsupported();
+  }
+
+  /**
+   * Starts continuous tracking, replacing any running, until `stopUpdates`; `setup` gives long-term
+   * awareness instead. The updates' positions reach `onLocationUpdate`, including after the system
+   * ended the app. Rejects with `NotAllowedError` without in-use permission, and on iOS with
+   * `NeedsUIError` off screen. Android's `foregroundService` rejects with `NotSupportedError`
+   * without the `background-updates` build setting, and with `NeedsUIError` when Android does not
+   * allow the service to start off screen.
+   */
+  async startUpdates(options: UpdateOptions = {}): Promise<void> {
+    validateUpdateOptions(options, "options");
+    return this.hasNativeTransport ? this.call("startUpdates", options) : web.unsupported();
+  }
+
+  stopUpdates(): Promise<void> {
+    return this.hasNativeTransport ? this.call("stopUpdates") : web.unsupported();
+  }
+
+  /** The options of the running updates, or null when none are running. */
+  getUpdates(): Promise<UpdateOptions | null> {
+    return this.hasNativeTransport ? this.call("getUpdates") : web.unsupported();
+  }
+
+  /**
+   * Monitors a circular region, replacing one with the same `id`, until `removeRegion`. Its entries
+   * and exits reach `onRegionTransition`, including when the system launches the app for one. A
+   * region starts outside, so a device already inside reports an entry. Rejects with
+   * `NotAllowedError` without precise location, and with `QuotaExceededError` beyond Apple's 20.
+   */
+  async addRegion(region: Region): Promise<void> {
+    const monitored = monitoredRegion(region);
+    return this.hasNativeTransport ? this.call("addRegion", monitored) : web.unsupported();
+  }
+
+  /** The monitored regions. */
+  getRegions(): Promise<MonitoredRegion[]> {
+    return this.hasNativeTransport ? this.call("getRegions") : web.unsupported();
+  }
+
+  async removeRegion(id: string): Promise<void> {
+    nonEmptyText(id, "id");
+    return this.hasNativeTransport ? this.call("removeRegion", { id }) : web.unsupported();
+  }
+
+  /** Receives the updates the Worker's `onLocationUpdate` receives, while the listening page or Worker runs. */
+  onLocationUpdate(listener: Listener<LocationUpdate>, error: ErrorListener = report): () => void {
+    return this.hasNativeTransport ? this.listen("onLocationUpdate", listener, error) : () => undefined;
+  }
+
+  /** Receives the transitions the Worker's `onRegionTransition` receives, while the listening page or Worker runs. */
+  onRegionTransition(listener: Listener<RegionTransition>, error: ErrorListener = report): () => void {
+    return this.hasNativeTransport ? this.listen("onRegionTransition", listener, error) : () => undefined;
+  }
+
+  /** Apple only: receives the visits the Worker's `onVisit` receives, while the listening page or Worker runs. */
+  onVisit(listener: Listener<Visit>, error: ErrorListener = report): () => void {
+    return this.hasNativeTransport ? this.listen("onVisit", listener, error) : () => undefined;
+  }
+
+  /** Receives the failures the Worker's `onLocationError` receives, while the listening page or Worker runs. */
+  onLocationError(listener: Listener<LocationErrorEvent>, error: ErrorListener = report): () => void {
+    return this.hasNativeTransport ? this.listen("onLocationError", listener, error) : () => undefined;
+  }
+}
+
+function report(error: DOMException): void {
+  console.error(error);
 }
 
 const unlimited = 0xffffffff;

package/src/options.ts

@@ -0,0 +1,54 @@
+import {
+  atLeastZero,
+  between,
+  flag,
+  nonEmptyText,
+  object,
+  oneOf,
+  positive,
+  text,
+  wholeAtLeastZero,
+} from "./checks.js";
+import type { Region } from "./types.js";
+
+/** Throws `TypeError` unless `config` is a configuration `setup` takes. */
+export const validateSetup = object({ significantChanges: flag, visits: flag });
+
+/** Throws `TypeError` unless `options` are options `requestPermission` takes. */
+export const validatePermissionRequest = object({
+  background: flag,
+  precision: oneOf("precise", "approximate"),
+  purpose: nonEmptyText,
+});
+
+/** Throws `TypeError` unless `options` are options `startUpdates` takes. */
+export const validateUpdateOptions = object({
+  activity: oneOf("default", "automotiveNavigation", "otherNavigation", "fitness", "airborne", "maritime"),
+  accuracy: oneOf("high", "balanced", "low"),
+  distance: atLeastZero,
+  interval: wholeAtLeastZero,
+  foregroundService: object(
+    { title: nonEmptyText, body: text, channel: nonEmptyText },
+    ["title", "body", "channel"],
+  ),
+});
+
+const REGION = object(
+  {
+    id: nonEmptyText,
+    latitude: between(-90, 90),
+    longitude: between(-180, 180),
+    radius: positive,
+    onEntry: flag,
+    onExit: flag,
+  },
+  ["id", "latitude", "longitude", "radius"],
+);
+
+/** `region`, with `onEntry` and `onExit` given. Throws `TypeError` unless it is a region to monitor. */
+export function monitoredRegion(region: Region): Required<Region> {
+  REGION(region, "region");
+  const { id, latitude, longitude, radius, onEntry = true, onExit = true } = region;
+  if (!onEntry && !onExit) throw new TypeError("region must report entry, exit or both");
+  return { id, latitude, longitude, radius, onEntry, onExit };
+}

package/src/types.ts

@@ -0,0 +1,173 @@
+export interface Coordinates {
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly accuracy: number;
+  readonly altitude: number | null;
+  readonly altitudeAccuracy: number | null;
+  readonly heading: number | null;
+  readonly speed: number | null;
+}
+
+export interface Position {
+  readonly coords: Coordinates;
+  readonly timestamp: number;
+}
+
+/** Options for `getCurrentPosition`, as the Geolocation API reads them. */
+export interface PositionOptions {
+  /** The age in milliseconds of a recent position to accept instead of a new one; 0 by default. */
+  readonly maximumAge?: number;
+  /** Milliseconds to wait for a position before rejecting with `TimeoutError`; unlimited by default. */
+  readonly timeout?: number;
+}
+
+export type PositionCallback = (position: Position) => void;
+export type PositionErrorCallback = (error: DOMException) => void;
+
+/**
+ * Long-term location awareness, which runs across launches and restarts, uses little power and shows
+ * no indicator: `setup` starts what it names and stops what it leaves out. Off screen it needs
+ * background permission, with which the system launches the app for its events.
+ */
+export interface SetupConfig {
+  /**
+   * Delivers moves of 500 metres or more, at most every 5 minutes, to `onLocationUpdate`, located
+   * from cellular and Wi-Fi rather than GPS: Apple's significant-change service, and on Android a
+   * low-power request with the same thresholds, which Android limits to a few an hour off screen.
+   */
+  readonly significantChanges?: boolean;
+  /** Apple only: delivers arrivals at and departures from places to `onVisit`. */
+  readonly visits?: boolean;
+}
+
+/** Whether the user granted a permission, denied it, or has not been asked. */
+export type Permission = "granted" | "denied" | "prompt";
+
+export type Precision = "precise" | "approximate";
+
+/** The app's location permission. */
+export interface LocationPermission {
+  /** Location while the app is in use. */
+  readonly inUse: Permission;
+  /** Location while it is not: Apple's Always, Android's "Allow all the time". The same as `inUse` on macOS. */
+  readonly background: Permission;
+  /** The precision the app gets, or would get once allowed. */
+  readonly precision: Precision;
+}
+
+/** What `requestPermission` asks for besides in-use permission. */
+export interface PermissionRequest {
+  /** Background permission, which needs the `background` build setting. */
+  readonly background?: boolean;
+  /**
+   * `"precise"` asks for precise location where the user allowed approximate: on Apple platforms
+   * temporarily, for `purpose`. `"approximate"` asks Android for approximate location only.
+   */
+  readonly precision?: Precision;
+  /** Apple only: the key in the `accuracy-purposes` build setting of the reason to show. */
+  readonly purpose?: string;
+}
+
+/**
+ * Apple only: the live update configuration, by Apple's name, which tunes when updates pause and
+ * how coordinates follow roads. `"maritime"` needs iOS 27 or macOS 27.
+ */
+export type Activity =
+  | "default"
+  | "automotiveNavigation"
+  | "otherNavigation"
+  | "fitness"
+  | "airborne"
+  | "maritime";
+
+/**
+ * `startUpdates` options, for continuous tracking such as a run or navigation, which can show the
+ * system's indicator: the blue pill on iOS with in-use permission, and the notification of
+ * Android's `foregroundService`. Each option is platform-specific: Apple's relaunching updates
+ * take only an `activity`.
+ */
+export interface UpdateOptions {
+  /** Apple only: `"default"` by default. */
+  readonly activity?: Activity;
+  /** Android only: the request's quality, precision traded against battery use; `"high"` by default. */
+  readonly accuracy?: "high" | "balanced" | "low";
+  /** Android only: metres the device moves before the next update; 0 by default. */
+  readonly distance?: number;
+  /** Android only: milliseconds between updates; 10 seconds by default. */
+  readonly interval?: number;
+  /**
+   * Android only: runs updates in a foreground service showing this notification, so they arrive at
+   * the requested rate off screen. Needs the `background-updates` build setting.
+   */
+  readonly foregroundService?: ServiceNotification;
+}
+
+/** Android only: the foreground service's notification, set from JavaScript so apps can translate it. */
+export interface ServiceNotification {
+  readonly title: string;
+  readonly body: string;
+  /** The name of the notification channel, which Android's settings show. */
+  readonly channel: string;
+}
+
+/** Positions from continuous updates or significant changes. */
+export interface LocationUpdate {
+  /** Oldest first: those that arrived while the Worker handled the previous update come together. */
+  readonly positions: readonly Position[];
+  /**
+   * Apple only, from iOS 18 and macOS 15: true on the last update before updates pause while the
+   * device is still. `positions` is empty when the update has no position.
+   */
+  readonly stationary?: boolean;
+}
+
+/** A circular region to monitor, with the same fields as the notifications plugin's `Region`. */
+export interface Region {
+  readonly id: string;
+  readonly latitude: number;
+  readonly longitude: number;
+  /** In metres. */
+  readonly radius: number;
+  /** Whether entering the region reaches `onRegionTransition`; true by default. */
+  readonly onEntry?: boolean;
+  /** Whether leaving it does; true by default. */
+  readonly onExit?: boolean;
+}
+
+/** A monitored region. */
+export interface MonitoredRegion extends Required<Region> {
+  /** Apple only: whether the device is inside the region, as the system last determined. */
+  readonly state?: "inside" | "outside" | "unknown";
+}
+
+/** An entry into or exit from a monitored region. */
+export interface RegionTransition {
+  readonly id: string;
+  readonly transition: "enter" | "exit";
+  /** Milliseconds since the epoch. */
+  readonly timestamp: number;
+}
+
+/** Apple only: an arrival at or departure from a place where the user stays. */
+export interface Visit {
+  readonly latitude: number;
+  readonly longitude: number;
+  /** In metres. */
+  readonly accuracy: number;
+  /** Milliseconds since the epoch, or null when unknown. */
+  readonly arrival: number | null;
+  /** Milliseconds since the epoch, or null before the user leaves. */
+  readonly departure: number | null;
+}
+
+/** A failure of a background location service. */
+export interface LocationErrorEvent {
+  /** A `DOMException` name, such as `"NotAllowedError"` or `"NotReadableError"`. */
+  readonly name: string;
+  readonly message: string;
+  /** The region's id, when the failure concerns one. */
+  readonly id?: string;
+}
+
+export type Listener<T> = (event: T) => void;
+export type ErrorListener = (error: DOMException) => void;

package/tokamak-plugin.json

@@ -1,21 +1,67 @@
 {
   "schemaVersion": 1,
   "id": "location",
+  "settings": {
+    "background": {
+      "kind": "boolean",
+      "default": false,
+      "description": "Declares background location permission: Apple's Always, Android's ACCESS_BACKGROUND_LOCATION"
+    },
+    "background-updates": {
+      "kind": "boolean",
+      "default": false,
+      "description": "Declares continuous updates off screen: iOS's location background mode, and Android's location foreground service"
+    },
+    "precision": {
+      "kind": "enum",
+      "values": ["precise", "approximate"],
+      "default": "precise",
+      "description": "The precision the app declares; approximate leaves out precise location"
+    },
+    "when-in-use-description": {
+      "kind": "string",
+      "description": "Apple only: the reason the in-use prompt shows"
+    },
+    "always-description": {
+      "kind": "string",
+      "description": "iOS only: the reason the Always prompt shows"
+    },
+    "accuracy-purposes": {
+      "kind": "map",
+      "of": "string",
+      "description": "Apple only: the reasons for temporary precise location, by purpose key"
+    }
+  },
+  "build": "build/index.mjs",
   "platforms": {
     "macos": {
       "class": "TokamakLocationPlugin",
-      "sources": ["apple/LocationPlugin.swift"],
-      "plist": "apple/macos/Info.plist"
+      "sources": [
+        "apple/LocationEvents.swift",
+        "apple/LocationPlugin.swift",
+        "apple/LocationRegions.swift",
+        "apple/LocationUpdates.swift"
+      ]
     },
     "ios": {
       "class": "TokamakLocationPlugin",
-      "sources": ["apple/LocationPlugin.swift"],
-      "plist": "apple/ios/Info.plist"
+      "sources": [
+        "apple/LocationEvents.swift",
+        "apple/LocationPlugin.swift",
+        "apple/LocationRegions.swift",
+        "apple/LocationUpdates.swift"
+      ]
     },
     "android": {
       "class": "com.tokamak.plugins.location.TokamakLocationPlugin",
-      "sources": ["android/LocationPlugin.kt"],
-      "manifest": "android/AndroidManifest.xml"
+      "sources": [
+        "android/LocationEvents.kt",
+        "android/LocationPlugin.kt",
+        "android/LocationReceiver.kt",
+        "android/LocationRegions.kt",
+        "android/LocationService.kt",
+        "android/LocationUpdates.kt"
+      ]
     }
   }
 }

package/web/index.ts

@@ -1,9 +1,10 @@
 import type {
+  LocationPermission,
   Position,
   PositionCallback,
   PositionErrorCallback,
   PositionOptions,
-} from "../src/index.js";
+} from "../src/types.js";
 
 export function getCurrentPosition(options: PositionOptions): Promise<Position> {
   return new Promise((resolve, reject) => {
@@ -38,6 +39,19 @@ export function watchPosition(
   };
 }
 
+/** The page's location permission, which the web has only for pages in use. */
+export async function permission(): Promise<LocationPermission> {
+  const permissions = (globalThis as { navigator?: { permissions?: Permissions } }).navigator?.permissions;
+  if (!permissions) throw new DOMException("The Permissions API is unavailable", "NotSupportedError");
+  const { state } = await permissions.query({ name: "geolocation" });
+  return { inUse: state, background: "denied", precision: "precise" };
+}
+
+/** Rejects as the web does for what only native apps have. */
+export function unsupported(): Promise<never> {
+  return Promise.reject(new DOMException("Native location is unavailable", "NotSupportedError"));
+}
+
 function browserLocationApi(): Geolocation {
   const root: { navigator?: { geolocation?: Geolocation } } = globalThis;
   const browserLocation = root.navigator?.geolocation;

package/android/AndroidManifest.xml

@@ -1,4 +0,0 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android">
-  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
-  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
-</manifest>

package/apple/ios/Info.plist

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-	<key>NSLocationWhenInUseUsageDescription</key>
-	<string>This app uses your location when you request location features.</string>
-</dict>
-</plist>

package/apple/macos/Info.plist

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-	<key>NSLocationUsageDescription</key>
-	<string>This app uses your location when you request location features.</string>
-</dict>
-</plist>