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

package/apple/LocationRegions.swift

@@ -0,0 +1,175 @@
+import CoreLocation
+import Foundation
+
+#if os(iOS)
+  import UIKit
+#endif
+
+/// The JSON of each monitored region, as `addRegion` received it, by id.
+private let regionsKey = "tokamak.location.regions"
+/// The ids of the regions whose last transition was an entry.
+private let insideKey = "tokamak.location.inside"
+/// `CLMonitor` monitors at most 20 conditions for an app, and reports no
+/// error beyond them.
+private let regionLimit = 20
+/// The monitor's name, which must be alphanumeric.
+private let monitorName = "TokamakLocation"
+
+/// Circular regions in one `CLMonitor`, which the plugin creates at launch
+/// and reads events from for the life of the process. The system launches the
+/// app for their events on iOS. Use it on the main thread.
+final class TokamakLocationRegions {
+  private let events: TokamakLocationEvents
+  private let defaults = UserDefaults.standard
+  private let monitor: Task<CLMonitor, Never>
+
+  init(events: TokamakLocationEvents) {
+    self.events = events
+    let monitor = Task { @MainActor in
+      await Self.firstUnlock()
+      return await CLMonitor(monitorName)
+    }
+    self.monitor = monitor
+    Task { @MainActor [weak self] in
+      do {
+        for try await event in await monitor.value.events {
+          self?.receive(event)
+        }
+      } catch {
+        self?.events.fail(
+          .locationUnavailable(error.localizedDescription))
+      }
+    }
+  }
+
+  /// The regions, by id.
+  private var regions: [String: [String: Any]] {
+    get {
+      defaults.data(forKey: regionsKey)
+        .flatMap { try? JSONSerialization.jsonObject(with: $0) as? [String: [String: Any]] } ?? [:]
+    }
+    set {
+      defaults.set(try? JSONSerialization.data(withJSONObject: newValue), forKey: regionsKey)
+    }
+  }
+
+  private var inside: Set<String> {
+    get { Set(defaults.stringArray(forKey: insideKey) ?? []) }
+    set { defaults.set(Array(newValue), forKey: insideKey) }
+  }
+
+  /// Monitors the region `region` describes, replacing one with the same id.
+  /// It starts outside, so a device already inside reports an entry, as on
+  /// Android.
+  func add(_ region: [String: Any]) async throws(TokamakPluginError) {
+    guard let id = region["id"] as? String, let radius = region["radius"] as? Double,
+      let latitude = region["latitude"] as? Double, let longitude = region["longitude"] as? Double
+    else {
+      throw TokamakPluginError(
+        name: "TypeError", message: "region must have an id, latitude, longitude and radius")
+    }
+    let monitor = await monitor.value
+    let monitored = await monitor.identifiers
+    guard monitored.count < regionLimit || monitored.contains(id) else {
+      throw TokamakPluginError(
+        name: "QuotaExceededError",
+        message: "The app monitors \(regionLimit) regions, the most the system allows")
+    }
+    let center = CLLocationCoordinate2D(latitude: latitude, longitude: longitude)
+    let condition = CLMonitor.CircularGeographicCondition(center: center, radius: radius)
+    regions[id] = region
+    inside.remove(id)
+    await monitor.add(condition, identifier: id, assuming: .unsatisfied)
+  }
+
+  func remove(_ id: String) async {
+    regions[id] = nil
+    inside.remove(id)
+    events.report([], region: id)
+    await monitor.value.remove(id)
+  }
+
+  /// The monitored regions, each with whether the device is inside it.
+  func all() async -> [[String: Any]] {
+    let monitor = await monitor.value
+    let regions = regions
+    var all: [[String: Any]] = []
+    for id in await monitor.identifiers {
+      guard var region = regions[id] else { continue }
+      region["state"] =
+        switch await monitor.record(for: id)?.lastEvent.state {
+        case .satisfied: "inside"
+        case .unsatisfied: "outside"
+        default: "unknown"
+        }
+      all.append(region)
+    }
+    return all
+  }
+
+  /// Reports the event's problems, and its transition when it changes whether the device is
+  /// inside the region, as events can repeat the state.
+  private func receive(_ event: CLMonitor.Event) {
+    let id = event.identifier
+    if #available(iOS 18, macOS 15, *) {
+      events.report(Self.problems(event), region: id)
+    }
+    guard let region = regions[id], event.state == .satisfied || event.state == .unsatisfied
+    else { return }
+    let entered = event.state == .satisfied
+    guard entered != inside.contains(id) else { return }
+    inside = entered ? inside.union([id]) : inside.subtracting([id])
+    if region[entered ? "onEntry" : "onExit"] as? Bool != false {
+      events.transition(id, entered: entered, at: event.date)
+    }
+  }
+
+  /// The problems that stop monitoring the region, which `event` names.
+  @available(iOS 18, macOS 15, *)
+  private static func problems(_ event: CLMonitor.Event) -> [TokamakPluginError] {
+    let flags = [
+      (event.authorizationDenied, "NotAllowedError", "Location permission was denied"),
+      (event.authorizationDeniedGlobally, "NotAllowedError", "Location services are off"),
+      (event.authorizationRestricted, "NotAllowedError", "Location is restricted on this device"),
+      (
+        event.insufficientlyInUse, "NotAllowedError",
+        "Regions need the app in use, or Always permission"
+      ),
+      (event.accuracyLimited, "NotAllowedError", "Regions need precise location"),
+      (event.conditionUnsupported, "NotSupportedError", "The device cannot monitor the region"),
+      (
+        event.conditionLimitExceeded, "QuotaExceededError",
+        "The app monitors the most regions the system allows"
+      ),
+      (
+        event.persistenceUnavailable, "NotReadableError",
+        "The system cannot store the app's regions"
+      ),
+    ]
+    return flags.filter(\.0).map { TokamakPluginError(name: $0.1, message: $0.2) }
+  }
+
+  /// Returns once the device has been unlocked since it booted, from when `CLMonitor` can read the
+  /// file that keeps its conditions, even while the device is locked.
+  @MainActor
+  private static func firstUnlock() async {
+    #if os(iOS)
+      let unlocked = NotificationCenter.default.notifications(
+        named: UIApplication.protectedDataDidBecomeAvailableNotification)
+      guard !unlockedSinceBoot() else { return }
+      for await _ in unlocked {
+        return
+      }
+    #endif
+  }
+
+  #if os(iOS)
+    /// Whether the device has been unlocked since it booted, as only then can a file protected
+    /// until the first unlock be written.
+    private static func unlockedSinceBoot() -> Bool {
+      let probe = FileManager.default.temporaryDirectory.appending(path: "TokamakLocation.unlocked")
+      let protection = Data.WritingOptions.completeFileProtectionUntilFirstUserAuthentication
+      return (try? Data().write(to: probe, options: protection)) != nil
+    }
+  #endif
+}

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.104",
   "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.104"
   },
   "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`);
+  }
+}