@tokamakdev/plugin-location 0.1.0-beta.128 → 0.1.0-beta.130

package/apple/LocationTypes.swift

@@ -0,0 +1,158 @@
+import CoreLocation
+import Foundation
+
+extension TokamakLocationPlugin {
+  struct Coordinates: Codable {
+    let latitude: Double
+    let longitude: Double
+    let accuracy: Double
+    let altitude: Double?
+    let altitudeAccuracy: Double?
+    let heading: Double?
+    let speed: Double?
+  }
+
+  struct Position: Codable {
+    let coords: Coordinates
+    /// Milliseconds since the epoch.
+    let timestamp: Double
+
+    init(_ location: CLLocation) {
+      let coordinate = location.coordinate
+      let altitude = location.verticalAccuracy >= 0
+      coords = Coordinates(
+        latitude: coordinate.latitude,
+        longitude: coordinate.longitude,
+        accuracy: location.horizontalAccuracy,
+        altitude: altitude ? location.altitude : nil,
+        altitudeAccuracy: altitude ? location.verticalAccuracy : nil,
+        heading: location.course >= 0 ? location.course : nil,
+        speed: location.speed >= 0 ? location.speed : nil
+      )
+      timestamp = location.timestamp.milliseconds
+    }
+  }
+
+  struct LocationUpdate: Codable {
+    let positions: [Position]
+    /// True on the last update before updates pause while the device is still.
+    let stationary: Bool?
+  }
+
+  enum Transition: String, Codable {
+    case enter
+    case exit
+  }
+
+  struct RegionTransition: Codable {
+    let id: String
+    let transition: Transition
+    /// Milliseconds since the epoch.
+    let timestamp: Double
+
+    init(id: String, entered: Bool, at date: Date) {
+      self.id = id
+      transition = entered ? .enter : .exit
+      timestamp = date.milliseconds
+    }
+  }
+
+  struct Visit: Codable {
+    let latitude: Double
+    let longitude: Double
+    let accuracy: Double
+    /// Milliseconds since the epoch, or nil when unknown.
+    let arrival: Double?
+    /// Milliseconds since the epoch, or nil before the user leaves.
+    let departure: Double?
+
+    init(_ visit: CLVisit) {
+      latitude = visit.coordinate.latitude
+      longitude = visit.coordinate.longitude
+      accuracy = visit.horizontalAccuracy
+      arrival = visit.arrivalDate == .distantPast ? nil : visit.arrivalDate.milliseconds
+      departure = visit.departureDate == .distantFuture ? nil : visit.departureDate.milliseconds
+    }
+  }
+
+  struct LocationErrorEvent: Codable {
+    let name: String
+    let message: String
+    /// The region's id, when the failure concerns one.
+    let id: String?
+  }
+
+  enum Permission: String, Codable {
+    case granted
+    case denied
+    case prompt
+  }
+
+  enum Precision: String, Codable {
+    case precise
+    case approximate
+  }
+
+  struct LocationPermission: Codable {
+    let inUse: Permission
+    let background: Permission
+    let precision: Precision
+  }
+
+  struct PermissionRequest: Codable {
+    let background: Bool?
+    let precision: Precision?
+    /// The key in the app's `NSLocationTemporaryUsageDescriptionDictionary` of the reason to show.
+    let purpose: String?
+  }
+
+  struct SetupConfig: Codable {
+    let significantChanges: Bool?
+    let visits: Bool?
+  }
+
+  /// The live update configuration, by Apple's name.
+  enum Activity: String, Codable {
+    case `default`
+    case automotiveNavigation
+    case otherNavigation
+    case fitness
+    case airborne
+    case maritime
+  }
+
+  struct UpdateOptions: Codable {
+    let activity: Activity?
+  }
+
+  struct Region: Codable {
+    let id: String
+    let latitude: Double
+    let longitude: Double
+    /// In metres.
+    let radius: Double
+    let onEntry: Bool?
+    let onExit: Bool?
+  }
+
+  enum RegionState: String, Codable {
+    case inside
+    case outside
+    case unknown
+  }
+
+  struct MonitoredRegion: Codable {
+    let id: String
+    let latitude: Double
+    let longitude: Double
+    let radius: Double
+    let onEntry: Bool
+    let onExit: Bool
+    /// Whether the device is inside the region, as the system last determined.
+    let state: RegionState
+  }
+}
+
+extension Date {
+  fileprivate var milliseconds: Double { timeIntervalSince1970 * 1000 }
+}

package/apple/LocationUpdates.swift

@@ -1,7 +1,7 @@
 import CoreLocation
 import Foundation
 
-/// The JSON of the running updates' options, as `startUpdates` received them.
+/// The JSON of the running updates' options.
 private let updatesKey = "tokamak.location.updates"
 
 /// Continuous updates from `CLLocationUpdate.liveUpdates`. iOS launches an app
@@ -22,16 +22,16 @@ final class TokamakLocationUpdates {
   }
 
   /// The options of the running updates, or nil.
-  var options: [String: Any]? {
+  var options: TokamakLocationPlugin.UpdateOptions? {
     defaults.data(forKey: updatesKey)
-      .flatMap { try? JSONSerialization.jsonObject(with: $0) as? [String: Any] }
+      .flatMap { try? JSONDecoder().decode(TokamakLocationPlugin.UpdateOptions.self, from: $0) }
   }
 
   /// Starts updates with `options`, replacing any running.
-  func start(_ options: [String: Any]) throws(TokamakPluginError) {
-    let configuration = try Self.configuration(options)
+  func start(_ options: TokamakLocationPlugin.UpdateOptions) throws(TokamakPluginError) {
+    let configuration = try Self.configuration(options.activity ?? .default)
     stop()
-    defaults.set(try? JSONSerialization.data(withJSONObject: options), forKey: updatesKey)
+    defaults.set(try? JSONEncoder().encode(options), forKey: updatesKey)
     run(configuration)
   }
 
@@ -39,7 +39,8 @@ final class TokamakLocationUpdates {
   /// 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 }
+    guard let options, let configuration = try? Self.configuration(options.activity ?? .default)
+    else { return }
     run(configuration)
   }
 
@@ -60,16 +61,9 @@ final class TokamakLocationUpdates {
         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))
-        }
+    task = events.task { [weak self] in
+      for try await update in CLLocationUpdate.liveUpdates(configuration) {
+        self?.receive(update)
       }
     }
   }
@@ -104,17 +98,17 @@ final class TokamakLocationUpdates {
     return flags.filter(\.0).map { TokamakPluginError(name: $0.1, message: $0.2) }
   }
 
-  /// The live update configuration `options` name as their `activity`.
+  /// The live update configuration of `activity`.
   private static func configuration(
-    _ options: [String: Any]
+    _ activity: TokamakLocationPlugin.Activity
   ) 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":
+    switch activity {
+    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, *) {
@@ -122,8 +116,6 @@ final class TokamakLocationUpdates {
         }
       #endif
       throw .notSupported("The maritime activity needs iOS 27 or macOS 27")
-    default:
-      throw TokamakPluginError(name: "TypeError", message: "activity is not a live configuration")
     }
   }
 

package/package.json

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

package/src/android.generated.ts

@@ -0,0 +1,170 @@
+// Generated by `tok plugin generate android`. Do not edit.
+import { NativeEndpoint, type JsonStream, type TokamakContext } from "@tokamakdev/plugin";
+import { defineEvent } from "@tokamakdev/plugin/events";
+
+export type Accuracy = "high" | "balanced" | "low";
+
+export interface Coordinates {
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly accuracy: number;
+  readonly altitude?: number;
+  readonly altitudeAccuracy?: number;
+  readonly heading?: number;
+  readonly speed?: number;
+}
+
+export interface LocationErrorEvent {
+  readonly name: string;
+  readonly message: string;
+}
+
+export interface LocationPermission {
+  readonly inUse: Permission;
+  readonly background: Permission;
+  readonly precision: Precision;
+}
+
+export interface LocationUpdate {
+  readonly positions: readonly Position[];
+}
+
+export interface MonitoredRegion {
+  readonly id: string;
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly radius: number;
+  readonly onEntry: boolean;
+  readonly onExit: boolean;
+}
+
+export type Permission = "granted" | "denied" | "prompt";
+
+export interface PermissionRequest {
+  readonly background?: boolean;
+  readonly precision?: Precision;
+}
+
+export interface Position {
+  readonly coords: Coordinates;
+  readonly timestamp: number;
+}
+
+export type Precision = "precise" | "approximate";
+
+export interface Region {
+  readonly id: string;
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly radius: number;
+  readonly onEntry?: boolean;
+  readonly onExit?: boolean;
+}
+
+export interface RegionTransition {
+  readonly id: string;
+  readonly transition: Transition;
+  readonly timestamp: number;
+}
+
+export interface ServiceNotification {
+  readonly title: string;
+  readonly body: string;
+  readonly channel: string;
+}
+
+export interface SetupConfig {
+  readonly significantChanges?: boolean;
+}
+
+export type Transition = "enter" | "exit";
+
+export interface UpdateOptions {
+  readonly accuracy?: Accuracy;
+  readonly distance?: number;
+  readonly interval?: number;
+  readonly foregroundService?: ServiceNotification;
+}
+
+/** The location plugin's native methods on Android. */
+export interface Android {
+  /** Applies long-term location awareness, replacing the previous configuration. */
+  setup(config: SetupConfig): Promise<void>;
+  /** The provider's last known position, when it is no older than `maximumAge`. */
+  recentPosition(maximumAge: number): Promise<Position | null>;
+  /** A new fix, or null when Android finds none. Cancelling the call stops locating. */
+  currentPosition(): Promise<Position | null>;
+  /** Positions as the device moves. */
+  watchPosition(): JsonStream<Position>;
+  /** The app's in-use and background permission, and the precision it gets. */
+  permission(): Promise<LocationPermission>;
+  /** Asks for the permission `request` names where the user has not answered. */
+  requestPermission(request?: PermissionRequest | null): Promise<LocationPermission>;
+  /** Whether location services are on for the device. */
+  servicesEnabled(): Promise<boolean>;
+  /** Opens the app's page in the system settings. */
+  openSettings(): Promise<void>;
+  /** Starts continuous updates, replacing any running, until `stopUpdates`. */
+  startUpdates(options?: UpdateOptions | null): Promise<void>;
+  stopUpdates(): Promise<void>;
+  /** The options of the running updates, or null when none are running. */
+  getUpdates(): Promise<UpdateOptions | null>;
+  /** Monitors a circular region, replacing one with the same `id`. */
+  addRegion(region: Region): Promise<void>;
+  /** The monitored regions. */
+  getRegions(): Promise<MonitoredRegion[]>;
+  removeRegion(id: string): Promise<void>;
+  /** The updates the Worker's listeners receive. */
+  onLocationUpdate(): JsonStream<LocationUpdate>;
+  /** The transitions the Worker's listeners receive. */
+  onRegionTransition(): JsonStream<RegionTransition>;
+  /** The failures the Worker's listeners receive. */
+  onLocationError(): JsonStream<LocationErrorEvent>;
+}
+
+/**
+ * The location plugin's native methods. Off Android they reject with `NotSupportedError`.
+ * Aborting `signal` cancels their calls.
+ */
+export function android(ctx: TokamakContext, signal?: AbortSignal): Android {
+  const endpoint = new NativeEndpoint(ctx, "location", ["android"], signal);
+  return {
+    setup: (config) => endpoint.call("setup", { config }),
+    recentPosition: (maximumAge) => endpoint.call("recentPosition", { maximumAge }),
+    currentPosition: () => endpoint.call("currentPosition"),
+    watchPosition: () => endpoint.stream("watchPosition", {}, "dropOldest"),
+    permission: () => endpoint.call("permission"),
+    requestPermission: (request) => endpoint.call("requestPermission", { request }),
+    servicesEnabled: () => endpoint.call("servicesEnabled"),
+    openSettings: () => endpoint.call("openSettings"),
+    startUpdates: (options) => endpoint.call("startUpdates", { options }),
+    stopUpdates: () => endpoint.call("stopUpdates"),
+    getUpdates: () => endpoint.call("getUpdates"),
+    addRegion: (region) => endpoint.call("addRegion", { region }),
+    getRegions: () => endpoint.call("getRegions"),
+    removeRegion: (id) => endpoint.call("removeRegion", { id }),
+    onLocationUpdate: () => endpoint.stream("onLocationUpdate", {}, "dropOldest"),
+    onRegionTransition: () => endpoint.stream("onRegionTransition"),
+    onLocationError: () => endpoint.stream("onLocationError"),
+  };
+}
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace -- events are declared by merging into Tokamak.Events.
+  namespace Tokamak {
+    interface Events {
+      "location.android.update": LocationUpdate;
+      "location.android.region": RegionTransition;
+      "location.android.error": LocationErrorEvent;
+    }
+  }
+}
+
+/** Receives continuous updates and significant changes, including those that start the app. */
+export const onUpdate = defineEvent("location.android.update", { platforms: ["android"] });
+
+/** Receives each region entry or exit, including one that starts the app. */
+export const onRegion = defineEvent("location.android.region", { platforms: ["android"] });
+
+/** Receives failures of background services, such as a region Android cannot monitor. */
+export const onError = defineEvent("location.android.error", { platforms: ["android"] });

package/src/apple.generated.ts

@@ -0,0 +1,183 @@
+// Generated by `tok plugin generate apple`. Do not edit.
+import { NativeEndpoint, type JsonStream, type TokamakContext } from "@tokamakdev/plugin";
+import { defineEvent } from "@tokamakdev/plugin/events";
+
+export type Activity = "default" | "automotiveNavigation" | "otherNavigation" | "fitness" | "airborne" | "maritime";
+
+export interface Coordinates {
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly accuracy: number;
+  readonly altitude?: number;
+  readonly altitudeAccuracy?: number;
+  readonly heading?: number;
+  readonly speed?: number;
+}
+
+export interface LocationErrorEvent {
+  readonly name: string;
+  readonly message: string;
+  readonly id?: string;
+}
+
+export interface LocationPermission {
+  readonly inUse: Permission;
+  readonly background: Permission;
+  readonly precision: Precision;
+}
+
+export interface LocationUpdate {
+  readonly positions: readonly Position[];
+  readonly stationary?: boolean;
+}
+
+export interface MonitoredRegion {
+  readonly id: string;
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly radius: number;
+  readonly onEntry: boolean;
+  readonly onExit: boolean;
+  readonly state: RegionState;
+}
+
+export type Permission = "granted" | "denied" | "prompt";
+
+export interface PermissionRequest {
+  readonly background?: boolean;
+  readonly precision?: Precision;
+  readonly purpose?: string;
+}
+
+export interface Position {
+  readonly coords: Coordinates;
+  readonly timestamp: number;
+}
+
+export type Precision = "precise" | "approximate";
+
+export interface Region {
+  readonly id: string;
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly radius: number;
+  readonly onEntry?: boolean;
+  readonly onExit?: boolean;
+}
+
+export type RegionState = "inside" | "outside" | "unknown";
+
+export interface RegionTransition {
+  readonly id: string;
+  readonly transition: Transition;
+  readonly timestamp: number;
+}
+
+export interface SetupConfig {
+  readonly significantChanges?: boolean;
+  readonly visits?: boolean;
+}
+
+export type Transition = "enter" | "exit";
+
+export interface UpdateOptions {
+  readonly activity?: Activity;
+}
+
+export interface Visit {
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly accuracy: number;
+  readonly arrival?: number;
+  readonly departure?: number;
+}
+
+/** The location plugin's native methods on iOS and macOS. */
+export interface Apple {
+  /** Applies long-term location awareness, replacing the previous configuration. */
+  setup(config: SetupConfig): Promise<void>;
+  /** Core Location's latest position, when it is no older than `maximumAge`. */
+  recentPosition(maximumAge: number): Promise<Position | null>;
+  /** A new fix. Cancelling the call stops locating. */
+  currentPosition(): Promise<Position>;
+  /** Positions as the device moves. */
+  watchPosition(): JsonStream<Position>;
+  /** The app's in-use and background permission, and the precision it gets. */
+  permission(): Promise<LocationPermission>;
+  /** Asks for the permission `request` names where the user has not answered. */
+  requestPermission(request?: PermissionRequest | null): Promise<LocationPermission>;
+  /** Whether location services are on for the device. */
+  servicesEnabled(): Promise<boolean>;
+  /** Opens the app's page in the system settings. */
+  openSettings(): Promise<void>;
+  /** Starts continuous updates, replacing any running, until `stopUpdates`. */
+  startUpdates(options?: UpdateOptions | null): Promise<void>;
+  stopUpdates(): Promise<void>;
+  /** The options of the running updates, or null when none are running. */
+  getUpdates(): Promise<UpdateOptions | null>;
+  /** Monitors a circular region, replacing one with the same `id`. */
+  addRegion(region: Region): Promise<void>;
+  /** The monitored regions. */
+  getRegions(): Promise<MonitoredRegion[]>;
+  removeRegion(id: string): Promise<void>;
+  /** The updates the Worker's listeners receive. */
+  onLocationUpdate(): JsonStream<LocationUpdate>;
+  /** The transitions the Worker's listeners receive. */
+  onRegionTransition(): JsonStream<RegionTransition>;
+  /** The visits the Worker's listeners receive. */
+  onVisit(): JsonStream<Visit>;
+  /** The failures the Worker's listeners receive. */
+  onLocationError(): JsonStream<LocationErrorEvent>;
+}
+
+/**
+ * The location plugin's native methods. Off iOS and macOS they reject with `NotSupportedError`.
+ * Aborting `signal` cancels their calls.
+ */
+export function apple(ctx: TokamakContext, signal?: AbortSignal): Apple {
+  const endpoint = new NativeEndpoint(ctx, "location", ["ios", "macos"], signal);
+  return {
+    setup: (config) => endpoint.call("setup", { config }),
+    recentPosition: (maximumAge) => endpoint.call("recentPosition", { maximumAge }),
+    currentPosition: () => endpoint.call("currentPosition"),
+    watchPosition: () => endpoint.stream("watchPosition", {}, "dropOldest"),
+    permission: () => endpoint.call("permission"),
+    requestPermission: (request) => endpoint.call("requestPermission", { request }),
+    servicesEnabled: () => endpoint.call("servicesEnabled"),
+    openSettings: () => endpoint.call("openSettings"),
+    startUpdates: (options) => endpoint.call("startUpdates", { options }),
+    stopUpdates: () => endpoint.call("stopUpdates"),
+    getUpdates: () => endpoint.call("getUpdates"),
+    addRegion: (region) => endpoint.call("addRegion", { region }),
+    getRegions: () => endpoint.call("getRegions"),
+    removeRegion: (id) => endpoint.call("removeRegion", { id }),
+    onLocationUpdate: () => endpoint.stream("onLocationUpdate", {}, "dropOldest"),
+    onRegionTransition: () => endpoint.stream("onRegionTransition"),
+    onVisit: () => endpoint.stream("onVisit"),
+    onLocationError: () => endpoint.stream("onLocationError"),
+  };
+}
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace -- events are declared by merging into Tokamak.Events.
+  namespace Tokamak {
+    interface Events {
+      "location.apple.update": LocationUpdate;
+      "location.apple.region": RegionTransition;
+      "location.apple.visit": Visit;
+      "location.apple.error": LocationErrorEvent;
+    }
+  }
+}
+
+/** Receives continuous updates and significant changes, including those that launch the app. */
+export const onUpdate = defineEvent("location.apple.update", { platforms: ["ios", "macos"] });
+
+/** Receives each region entry or exit, including one that launches the app. */
+export const onRegion = defineEvent("location.apple.region", { platforms: ["ios", "macos"] });
+
+/** Receives each arrival at or departure from a place, including one that launches the app. */
+export const onVisit = defineEvent("location.apple.visit", { platforms: ["ios", "macos"] });
+
+/** Receives failures of background services, such as a region Core Location cannot monitor. */
+export const onError = defineEvent("location.apple.error", { platforms: ["ios", "macos"] });

package/src/events.ts

@@ -0,0 +1,31 @@
+import type { Listener } from "@tokamakdev/plugin/events";
+
+import * as android from "./android.generated.js";
+import * as apple from "./apple.generated.js";
+import type { LocationErrorEvent, LocationUpdate, RegionTransition, Visit } from "./types.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 function onLocationUpdate(listener: Listener<LocationUpdate>): void {
+  apple.onUpdate(listener);
+  android.onUpdate(listener);
+}
+
+/** Receives each region entry or exit, including one that launches the app. */
+export function onRegionTransition(listener: Listener<RegionTransition>): void {
+  apple.onRegion(listener);
+  android.onRegion(listener);
+}
+
+/** Apple only: receives each arrival at or departure from a place, including one that launches the app. */
+export function onVisit(listener: Listener<Visit>): void {
+  apple.onVisit(listener);
+}
+
+/** Receives failures of background location services, such as a region the system cannot monitor. */
+export function onLocationError(listener: Listener<LocationErrorEvent>): void {
+  apple.onError(listener);
+  android.onError(listener);
+}