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

package/apple/LocationUpdates.swift

@@ -0,0 +1,137 @@
+import CoreLocation
+import Foundation
+
+/// The JSON of the running updates' options, as `startUpdates` received them.
+private let updatesKey = "tokamak.location.updates"
+
+/// Continuous updates from `CLLocationUpdate.liveUpdates`. iOS launches an app
+/// it ended while they ran for the next update, so the options persist until
+/// `stop`, and `resume` starts them again at launch. Use it on the main thread.
+final class TokamakLocationUpdates {
+  private let events: TokamakLocationEvents
+  private let defaults = UserDefaults.standard
+  private var task: Task<Void, Never>?
+  #if os(iOS)
+    /// Keeps the app in use while updates run off screen, with the location
+    /// indicator.
+    private var session: CLBackgroundActivitySession?
+  #endif
+
+  init(events: TokamakLocationEvents) {
+    self.events = events
+  }
+
+  /// The options of the running updates, or nil.
+  var options: [String: Any]? {
+    defaults.data(forKey: updatesKey)
+      .flatMap { try? JSONSerialization.jsonObject(with: $0) as? [String: Any] }
+  }
+
+  /// Starts updates with `options`, replacing any running.
+  func start(_ options: [String: Any]) throws(TokamakPluginError) {
+    let configuration = try Self.configuration(options)
+    stop()
+    defaults.set(try? JSONSerialization.data(withJSONObject: options), forKey: updatesKey)
+    run(configuration)
+  }
+
+  /// Starts the updates that ran when the app last ended. The system keeps
+  /// their session for only a few seconds after it launches the app, so call
+  /// it before launch finishes.
+  func resume() {
+    guard let options, let configuration = try? Self.configuration(options) else { return }
+    run(configuration)
+  }
+
+  func stop() {
+    defaults.removeObject(forKey: updatesKey)
+    task?.cancel()
+    task = nil
+    #if os(iOS)
+      session?.invalidate()
+      session = nil
+    #endif
+    events.report([])
+  }
+
+  private func run(_ configuration: CLLocationUpdate.LiveConfiguration) {
+    #if os(iOS)
+      if Self.declaresBackgroundMode {
+        session = CLBackgroundActivitySession()
+      }
+    #endif
+    task = Task { @MainActor [weak self] in
+      do {
+        for try await update in CLLocationUpdate.liveUpdates(configuration) {
+          self?.receive(update)
+        }
+      } catch {
+        if !Task.isCancelled {
+          self?.events.fail(
+            .locationUnavailable(error.localizedDescription))
+        }
+      }
+    }
+  }
+
+  private func receive(_ update: CLLocationUpdate) {
+    guard #available(iOS 18, macOS 15, *) else {
+      if let location = update.location {
+        events.update(location)
+      }
+      return
+    }
+    events.report(Self.problems(update))
+    if update.location != nil || update.stationary {
+      events.update(update.location, stationary: update.stationary)
+    }
+  }
+
+  /// The problems that suspend updates, which `update` names.
+  @available(iOS 18, macOS 15, *)
+  private static func problems(_ update: CLLocationUpdate) -> [TokamakPluginError] {
+    let flags = [
+      (update.authorizationDenied, "NotAllowedError", "Location permission was denied"),
+      (update.authorizationDeniedGlobally, "NotAllowedError", "Location services are off"),
+      (update.authorizationRestricted, "NotAllowedError", "Location is restricted on this device"),
+      (
+        update.insufficientlyInUse, "NotAllowedError",
+        "Updates need the app in use, or Always permission"
+      ),
+      (update.accuracyLimited, "NotAllowedError", "Approximate location limits updates"),
+      (update.locationUnavailable, "NotReadableError", "Location is unavailable"),
+    ]
+    return flags.filter(\.0).map { TokamakPluginError(name: $0.1, message: $0.2) }
+  }
+
+  /// The live update configuration `options` name as their `activity`.
+  private static func configuration(
+    _ options: [String: Any]
+  ) throws(TokamakPluginError) -> CLLocationUpdate.LiveConfiguration {
+    switch options["activity"] as? String ?? "default" {
+    case "default": return .default
+    case "automotiveNavigation": return .automotiveNavigation
+    case "otherNavigation": return .otherNavigation
+    case "fitness": return .fitness
+    case "airborne": return .airborne
+    case "maritime":
+      // The SDKs that have `maritime` ship with Swift 6.4.
+      #if compiler(>=6.4)
+        if #available(iOS 27, macOS 27, *) {
+          return .maritime
+        }
+      #endif
+      throw .notSupported("The maritime activity needs iOS 27 or macOS 27")
+    default:
+      throw TokamakPluginError(name: "TypeError", message: "activity is not a live configuration")
+    }
+  }
+
+  #if os(iOS)
+    /// Whether the app declares the `location` background mode, as the
+    /// `background-updates` build setting does.
+    private static let declaresBackgroundMode =
+      (Bundle.main.object(forInfoDictionaryKey: "UIBackgroundModes") as? [String])?
+      .contains("location") == true
+  #endif
+}

package/build/declarations.d.mts

@@ -0,0 +1,19 @@
+/** The location plugin's build settings, with their defaults applied. */
+export interface Settings {
+  background: boolean;
+  "background-updates": boolean;
+  precision: "precise" | "approximate";
+  "when-in-use-description"?: string;
+  "always-description"?: string;
+  "accuracy-purposes"?: Record<string, string>;
+}
+
+/** The file that declares what the settings ask for, the plugin section key naming it, and notices. */
+export interface Declarations {
+  key: "plist" | "manifest";
+  name: string;
+  contents: string;
+  notices: string[];
+}
+
+export function declarations(platform: string, settings: Settings): Declarations | { problems: string[] };

package/build/declarations.mjs

@@ -0,0 +1,105 @@
+// The location plugin's declarations, from its build settings: the Info.plist on Apple platforms
+// and the Android manifest.
+
+const WHEN_IN_USE = "This app uses your location when you request location features.";
+const ALWAYS = "This app uses your location in the background for location features you turn on.";
+
+/**
+ * The file that declares what `settings` ask for on `platform`, the plugin section key that names
+ * it, and notices for the build; or the problems with the settings.
+ */
+export function declarations(platform, settings) {
+  if (settings["always-description"] !== undefined && !settings.background) {
+    return { problems: ["always-description needs background, which declares the permission it describes"] };
+  }
+  if (platform === "android") {
+    return { key: "manifest", name: "AndroidManifest.xml", contents: androidManifest(settings), notices: [] };
+  }
+  const notices =
+    platform === "macos" && settings.precision === "approximate"
+      ? ["macOS has no declaration of approximate location, so precision approximate applies to iOS and Android only"]
+      : [];
+  return { key: "plist", name: "Info.plist", contents: plist(appleKeys(platform, settings)), notices };
+}
+
+/** The Info.plist keys of `settings` on the Apple `platform`. */
+function appleKeys(platform, settings) {
+  const whenInUse = settings["when-in-use-description"] ?? WHEN_IN_USE;
+  const purposes = settings["accuracy-purposes"] ?? {};
+  const temporary = Object.keys(purposes).length > 0 ? { NSLocationTemporaryUsageDescriptionDictionary: purposes } : {};
+  if (platform === "macos") {
+    // macOS reads NSLocationUsageDescription, and its SDK headers name the iOS keys.
+    return {
+      NSLocationUsageDescription: whenInUse,
+      NSLocationWhenInUseUsageDescription: whenInUse,
+      NSLocationAlwaysAndWhenInUseUsageDescription: whenInUse,
+      ...temporary,
+    };
+  }
+  const keys = { NSLocationWhenInUseUsageDescription: whenInUse };
+  if (settings.background) keys.NSLocationAlwaysAndWhenInUseUsageDescription = settings["always-description"] ?? ALWAYS;
+  if (settings["background-updates"]) keys.UIBackgroundModes = ["location"];
+  if (settings.precision === "approximate") keys.NSLocationDefaultAccuracyReduced = true;
+  return { ...keys, ...temporary };
+}
+
+/** The Android manifest of `settings`. */
+function androidManifest(settings) {
+  const permissions = ["ACCESS_COARSE_LOCATION", "RECEIVE_BOOT_COMPLETED"];
+  if (settings.precision !== "approximate") permissions.push("ACCESS_FINE_LOCATION");
+  if (settings.background) permissions.push("ACCESS_BACKGROUND_LOCATION");
+  if (settings["background-updates"]) permissions.push("FOREGROUND_SERVICE", "FOREGROUND_SERVICE_LOCATION");
+  const service = settings["background-updates"]
+    ? [
+        '    <service android:name="com.tokamak.plugins.location.TokamakLocationService" android:exported="false"',
+        '        android:foregroundServiceType="location" />',
+      ]
+    : [];
+  return [
+    '<manifest xmlns:android="http://schemas.android.com/apk/res/android">',
+    ...permissions.map((name) => `  <uses-permission android:name="android.permission.${name}" />`),
+    "  <application>",
+    ...service,
+    '    <receiver android:name="com.tokamak.plugins.location.TokamakLocationReceiver" android:exported="false" />',
+    '    <receiver android:name="com.tokamak.plugins.location.TokamakLocationBootReceiver" android:exported="false">',
+    "      <intent-filter>",
+    '        <action android:name="android.intent.action.BOOT_COMPLETED" />',
+    '        <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />',
+    "      </intent-filter>",
+    "    </receiver>",
+    "  </application>",
+    "</manifest>",
+    "",
+  ].join("\n");
+}
+
+/** `keys` as an XML property list. */
+function plist(keys) {
+  return [
+    '<?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">',
+    ...element(keys, ""),
+    "</plist>",
+    "",
+  ].join("\n");
+}
+
+/** The lines of `value` as a property list element, indented by `indent`. */
+function element(value, indent) {
+  if (typeof value === "boolean") return [`${indent}<${String(value)}/>`];
+  if (typeof value === "string") return [`${indent}<string>${escaped(value)}</string>`];
+  const inner = `${indent}\t`;
+  if (Array.isArray(value)) {
+    return [`${indent}<array>`, ...value.flatMap((item) => element(item, inner)), `${indent}</array>`];
+  }
+  const entries = Object.entries(value).flatMap(([key, item]) => [
+    `${inner}<key>${escaped(key)}</key>`,
+    ...element(item, inner),
+  ]);
+  return [`${indent}<dict>`, ...entries, `${indent}</dict>`];
+}
+
+function escaped(text) {
+  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}

package/build/index.mjs

@@ -0,0 +1,17 @@
+// The location plugin's build script: tok runs it for each platform with the plugin's resolved
+// build settings on stdin. It writes the plugin's Info.plist or Android manifest into `output`
+// and prints the key that names it.
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { declarations } from "./declarations.mjs";
+
+const { platform, settings, output } = JSON.parse(readFileSync(0, "utf8"));
+const { key, name, contents, notices, problems } = declarations(platform, settings);
+if (problems) {
+  console.error(problems.join("\n"));
+  process.exit(1);
+}
+for (const notice of notices) console.error(notice);
+const path = join(output, name);
+writeFileSync(path, contents);
+console.log(JSON.stringify({ [key]: path }));

package/events/index.ts

@@ -0,0 +1,18 @@
+import { defineEvent } from "@tokamakdev/plugin/events";
+
+import type { LocationErrorEvent, LocationUpdate, RegionTransition, Visit } from "../src/index.js";
+
+/**
+ * Receives the positions of continuous updates and significant changes in native builds: on
+ * screen, off screen, or after the system launches the app for them.
+ */
+export const onLocationUpdate = defineEvent<LocationUpdate>("location.update");
+
+/** Receives each region entry or exit, including one that launches the app. */
+export const onRegionTransition = defineEvent<RegionTransition>("location.region");
+
+/** Apple only: receives each arrival at or departure from a place, including one that launches the app. */
+export const onVisit = defineEvent<Visit>("location.visit");
+
+/** Receives failures of background location services, such as a region the system cannot monitor. */
+export const onLocationError = defineEvent<LocationErrorEvent>("location.error");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin-location",
-  "version": "0.1.0-beta.102",
+  "version": "0.1.0-beta.103",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -8,14 +8,17 @@
   },
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./events": "./events/index.ts"
   },
   "peerDependencies": {
-    "@tokamakdev/plugin": "0.1.0-beta.102"
+    "@tokamakdev/plugin": "0.1.0-beta.103"
   },
   "files": [
     "android",
     "apple",
+    "build",
+    "events",
     "src",
     "web",
     "tokamak-plugin.json",

package/src/checks.ts

@@ -0,0 +1,65 @@
+/** Checks of the values the plugin's methods take, which throw `TypeError` naming the value. */
+export type Check = (value: unknown, path: string) => void;
+
+/** Checks that `value` is an object, then each field `checks` names that it has or `required` lists. */
+export function object(checks: Readonly<Record<string, Check>>, required: readonly string[] = []): Check {
+  return (value, path) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new TypeError(`${path} must be an object`);
+    }
+    for (const [key, check] of Object.entries(checks)) {
+      const field = (value as Record<string, unknown>)[key];
+      if (field !== undefined || required.includes(key)) check(field, `${path}.${key}`);
+    }
+  };
+}
+
+export function flag(value: unknown, path: string): void {
+  if (typeof value !== "boolean") throw new TypeError(`${path} must be a boolean`);
+}
+
+export function text(value: unknown, path: string): void {
+  if (typeof value !== "string") throw new TypeError(`${path} must be a string`);
+}
+
+export function nonEmptyText(value: unknown, path: string): void {
+  if (typeof value !== "string" || value === "") throw new TypeError(`${path} must be a non-empty string`);
+}
+
+export function oneOf(...allowed: readonly string[]): Check {
+  return (value, path) => {
+    if (!allowed.includes(value as string)) {
+      throw new TypeError(`${path} must be one of ${allowed.map((name) => `"${name}"`).join(", ")}`);
+    }
+  };
+}
+
+/** A finite number of at least 0. */
+export function atLeastZero(value: unknown, path: string): void {
+  if (!(typeof value === "number" && Number.isFinite(value) && value >= 0)) {
+    throw new TypeError(`${path} must be a finite number of at least 0`);
+  }
+}
+
+/** A whole number of at least 0. */
+export function wholeAtLeastZero(value: unknown, path: string): void {
+  if (!(Number.isSafeInteger(value) && (value as number) >= 0)) {
+    throw new TypeError(`${path} must be a whole number of at least 0`);
+  }
+}
+
+/** A number from `min` to `max`. */
+export function between(min: number, max: number): Check {
+  return (value, path) => {
+    if (!(typeof value === "number" && value >= min && value <= max)) {
+      throw new TypeError(`${path} must be a number from ${String(min)} to ${String(max)}`);
+    }
+  };
+}
+
+/** A finite number greater than 0. */
+export function positive(value: unknown, path: string): void {
+  if (!(typeof value === "number" && Number.isFinite(value) && value > 0)) {
+    throw new TypeError(`${path} must be a finite number greater than 0`);
+  }
+}

package/src/index.ts

@@ -1,37 +1,43 @@
 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 what runs at every launch, replacing the previous configuration, which the plugin keeps
+   * and applies again at each start. Rejects with `TypeError`, changing nothing, when a value is
+   * invalid.
+   */
+  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 +50,97 @@ 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 updates, replacing any running, until `stopUpdates`. Their 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 };
+}