@octane-xplat/geolocation 0.14.0 → 0.16.0

package/README.md

@@ -6,7 +6,8 @@ pnpm add @octane-xplat/geolocation
 
 Device geolocation behind one capability object. iOS and Android run
 `@nativescript/geolocation`; web uses `navigator.geolocation`; the macOS
-AppKit dev host reports `supported: false` (no CoreLocation bridge).
+AppKit target uses Core Location through a package-owned native facade. Hosts
+without that facade or location purpose strings report `supported: false`.
 
 ```ts
 import { geolocation } from '@octane-xplat/geolocation'
@@ -23,7 +24,74 @@ implementation exists on this target, `ensure()` resolves
 defers the prompt), and `impl` is the service once usable. Nullable
 `altitude`/`heading`/`speed` mean the platform did not report them.
 
-Guide: [Using device features](../../docs/platform/platform-services.md);
-per-target availability: [platform notes](../../docs/notes/platform-notes.md).
+On iOS and Android, position failures preserve the plugin's original error;
+a numeric `code` is not guaranteed. Web and macOS failures use codes 1
+(denied), 2 (unavailable), and 3 (timeout). Handle an unclassified failure too:
+
+```ts
+import { geolocation } from '@octane-xplat/geolocation'
+
+if ((await geolocation.ensure()) === 'granted') {
+	try {
+		const position = await geolocation.impl!.getCurrentPosition()
+		console.log(position.latitude, position.longitude)
+	} catch (error) {
+		const code = (error as { code?: number }).code
+		console.log(code === undefined ? 'Location failed' : `Location failed: ${code}`)
+	}
+}
+```
+
+Guide: [Using device features](../../docs/platform/platform-services.md)
+per-target availability: [platform notes](../../.agents/docs/notes/platform-notes.md).
 Exercised by the harness `Services` screen
 ([`packages/app/src/Services.tsrx`](../app/src/Services.tsrx)).
+
+## macOS host setup
+
+The existing Xplat native build discovers this package's `platforms/macos`
+sources and links CoreLocation. Add both purpose strings to the application
+Info.plist before requesting permission. An unsigned command-line host without
+an application bundle remains unsupported.
+
+```xml
+<key>NSLocationUsageDescription</key>
+<string>Show places near your current location.</string>
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>Show places near your current location while you use the app.</string>
+```
+
+Sandboxed applications also need the location entitlement in their signing
+entitlements file. The application owns its purpose text and signing settings.
+
+```xml
+<key>com.apple.security.personal-information.location</key>
+<true/>
+```
+
+Location denial or disabled system Location Services returns `denied`. A
+permission request with no decision after 30 seconds returns `unsupported`
+and can be retried. Position failures reject with code 1 (denied), 2
+(unavailable), or 3 (timeout). Times are milliseconds; omitted timeout waits
+without a deadline, and omitted maximumAge requires a fresh fix.
+
+```ts
+import { geolocation } from '@octane-xplat/geolocation'
+
+if ((await geolocation.ensure()) === 'granted') {
+	try {
+		const position = await geolocation.impl!.getCurrentPosition({
+			enableHighAccuracy: true,
+			timeout: 10000,
+			maximumAge: 5000,
+		})
+		console.log(position.latitude, position.longitude)
+	} catch (error) {
+		console.log('Location failed', (error as { code?: number }).code)
+	}
+}
+```
+
+Automated coverage checks native delegate cleanup and the service adapter.
+Real AppKit permission prompts, signed/sandboxed delivery, and physical location
+accuracy still require the manual test plan in the implementation commit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/geolocation",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Device geolocation for Octane xplat — matching web + NativeScript implementations",
   "keywords": [
     "android",
@@ -22,15 +22,30 @@
     "directory": "packages/geolocation"
   },
   "files": [
-    "src"
+    "src",
+    "platforms",
+    "types",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
   ],
   "type": "module",
   "exports": {
     ".": {
-      "macos": "./src/index.macos.ts",
+      "macos": {
+        "types": "./types/generated/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "types": "./types/generated/index.d.ts",
       "default": "./src/index.ts"
     },
-    "./*": "./src/*"
+    "./*": {
+      "types": "./types/generated/*.d.ts",
+      "default": "./src/*"
+    },
+    "./*.ts": {
+      "types": "./types/generated/*.d.ts",
+      "default": "./src/*.ts"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -39,9 +54,13 @@
     "@nativescript/geolocation": "9.0.0"
   },
   "devDependencies": {
-    "@nativescript-community/octane": "0.2.4",
+    "@nativescript-community/octane": "0.2.5",
     "@nativescript/core": "9.1.3",
-    "octane": "0.11.0"
+    "@nativescript/types": "9.1.4",
+    "@tsrx/typescript-plugin": "0.4.11",
+    "octane": "0.11.0",
+    "tsrx-typegen": "0.3.1",
+    "typescript": "5.9.3"
   },
   "peerDependencies": {
     "@nativescript-community/octane": ">=0.2.1 <1",
@@ -62,7 +81,19 @@
       "ios": "9.1.0"
     }
   },
+  "xplat": {
+    "macos": {
+      "frameworks": [
+        "Foundation",
+        "CoreLocation"
+      ]
+    }
+  },
   "scripts": {
-    "test:packed": "node tests/packed-consumer.mjs"
+    "test:packed": "node tests/packed-consumer.mjs",
+    "test": "node --experimental-strip-types --test tests/geolocation.macos.test.ts",
+    "test:macos": "node tests/verify-macos.mjs && node tests/verify-host.mjs",
+    "typegen": "tsrx-typegen --project tsconfig.types.json",
+    "pack:check": "tsrx-typegen --pack-check"
   }
 }

package/platforms/macos/include/XplatGeolocation.h

@@ -0,0 +1,8 @@
+#import <Foundation/Foundation.h>
+
+@interface XplatGeolocation : NSObject
++ (BOOL)isAvailable;
++ (void)ensure:(void (^)(NSString *result))completion;
++ (void)position:(BOOL)highAccuracy timeout:(double)timeout maximumAge:(double)maximumAge
+      completion:(void (^)(NSString *positionJSON, NSInteger code, NSString *message))completion;
+@end

package/platforms/macos/src/XplatGeolocation.m

@@ -0,0 +1,125 @@
+#import "XplatGeolocation.h"
+#import <CoreLocation/CoreLocation.h>
+
+// Each operation owns its manager/delegate until completion. All access and JS
+// callbacks occur on the main queue; concurrent callers cannot replace callbacks.
+@interface XplatLocationRequest : NSObject <CLLocationManagerDelegate>
+@property(nonatomic, strong) CLLocationManager *manager;
+@property(nonatomic, copy) void (^permission)(NSString *);
+@property(nonatomic, copy) void (^position)(NSString *, NSInteger, NSString *);
+@property(nonatomic) BOOL finished;
+@property(nonatomic) BOOL started;
+@property(nonatomic) double maximumAge;
+@property(nonatomic, strong) NSDate *startedAt;
+- (void)authorization;
+- (void)finish:(CLLocation *)location code:(NSInteger)code message:(NSString *)message;
+@end
+
+static NSMutableSet<XplatLocationRequest *> *requests;
+static CLLocation *cachedLocation;
+
+@implementation XplatLocationRequest
+- (void)finish:(CLLocation *)location code:(NSInteger)code message:(NSString *)message {
+    if (self.finished) return;
+    self.finished = YES;
+    [self.manager stopUpdatingLocation];
+    self.manager.delegate = nil;
+    NSDictionary *value = nil;
+    if (location) {
+        cachedLocation = location;
+        value = @{@"latitude": @(location.coordinate.latitude), @"longitude": @(location.coordinate.longitude),
+                  @"accuracy": @(location.horizontalAccuracy),
+                  @"altitude": location.verticalAccuracy >= 0 ? @(location.altitude) : NSNull.null,
+                  @"heading": location.course >= 0 ? @(location.course) : NSNull.null,
+                  @"speed": location.speed >= 0 ? @(location.speed) : NSNull.null,
+                  @"timestamp": @(location.timestamp.timeIntervalSince1970 * 1000)};
+    }
+    if (self.permission) self.permission(code == 0 ? @"granted" : code == 1 ? @"denied" : @"unsupported");
+    NSString *json = value ? [[NSString alloc] initWithData:[NSJSONSerialization dataWithJSONObject:value options:0 error:nil] encoding:NSUTF8StringEncoding] : nil;
+    if (self.position) self.position(json, code, message ?: @"");
+    self.permission = nil;
+    self.position = nil;
+    [requests removeObject:self];
+}
+- (void)authorization {
+    if (self.finished) return;
+    CLAuthorizationStatus status = self.manager.authorizationStatus;
+    if (status == kCLAuthorizationStatusDenied || status == kCLAuthorizationStatusRestricted ||
+        !CLLocationManager.locationServicesEnabled) {
+        [self finish:nil code:1 message:@"Location permission denied or services disabled"];
+    } else if (status == kCLAuthorizationStatusAuthorizedAlways) {
+        if (self.permission) {
+            [self finish:nil code:0 message:nil];
+        } else if (!self.started) {
+            self.started = YES;
+            double age = -cachedLocation.timestamp.timeIntervalSinceNow * 1000;
+            if (cachedLocation && self.maximumAge > 0 && age >= 0 && age <= self.maximumAge) {
+                [self finish:cachedLocation code:0 message:nil];
+            } else {
+                [self.manager startUpdatingLocation];
+            }
+        }
+    }
+}
+- (void)locationManagerDidChangeAuthorization:(CLLocationManager *)manager { [self authorization]; }
+- (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray<CLLocation *> *)locations {
+    CLLocation *location = locations.lastObject;
+    if (!location || location.horizontalAccuracy < 0) return;
+    double age = -location.timestamp.timeIntervalSinceNow * 1000;
+    // A zero maximumAge must not reuse a fix obtained before this request.
+    if (self.maximumAge > 0 ? age > self.maximumAge : [location.timestamp compare:self.startedAt] == NSOrderedAscending) return;
+    [self finish:location code:0 message:nil];
+}
+- (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error {
+    if ([error.domain isEqualToString:kCLErrorDomain] && error.code == kCLErrorLocationUnknown) return;
+    NSInteger code = [error.domain isEqualToString:kCLErrorDomain] && error.code == kCLErrorDenied ? 1 : 2;
+    [self finish:nil code:code message:code == 1 ? @"Location permission denied" : @"Location unavailable"];
+}
+@end
+
+@implementation XplatGeolocation
++ (BOOL)isAvailable {
+    NSBundle *bundle = NSBundle.mainBundle;
+    NSString *purpose = [bundle objectForInfoDictionaryKey:@"NSLocationUsageDescription"];
+    NSString *whenInUse = [bundle objectForInfoDictionaryKey:@"NSLocationWhenInUseUsageDescription"];
+    return bundle.bundleIdentifier.length > 0 && [purpose isKindOfClass:NSString.class] && purpose.length > 0 &&
+           [whenInUse isKindOfClass:NSString.class] && whenInUse.length > 0;
+}
++ (void)begin:(BOOL)high timeout:(double)timeout maximumAge:(double)maximumAge
+    permission:(void (^)(NSString *))permission position:(void (^)(NSString *, NSInteger, NSString *))position {
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if (![self isAvailable]) {
+            if (permission) permission(@"unsupported");
+            if (position) position(nil, 2, @"Location host is not configured");
+            return;
+        }
+        if (!requests) requests = NSMutableSet.new;
+        XplatLocationRequest *request = XplatLocationRequest.new;
+        request.permission = permission;
+        request.position = position;
+        request.maximumAge = maximumAge;
+        request.startedAt = NSDate.date;
+        request.manager = CLLocationManager.new;
+        request.manager.desiredAccuracy = high ? kCLLocationAccuracyBest : kCLLocationAccuracyThreeKilometers;
+        [requests addObject:request];
+        request.manager.delegate = request;
+        [request authorization];
+        if (request.finished) return;
+        if (request.manager.authorizationStatus == kCLAuthorizationStatusNotDetermined) {
+            [request.manager requestWhenInUseAuthorization];
+        }
+        if (timeout >= 0) {
+            __weak XplatLocationRequest *weakRequest = request;
+            dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(MIN(timeout, (double)INT64_MAX / NSEC_PER_MSEC) * NSEC_PER_MSEC)),
+                           dispatch_get_main_queue(), ^{ [weakRequest finish:nil code:3 message:@"Location request timed out"]; });
+        }
+    });
+}
++ (void)ensure:(void (^)(NSString *))completion {
+    [self begin:NO timeout:30000 maximumAge:0 permission:completion position:nil];
+}
++ (void)position:(BOOL)highAccuracy timeout:(double)timeout maximumAge:(double)maximumAge
+      completion:(void (^)(NSString *, NSInteger, NSString *))completion {
+    [self begin:highAccuracy timeout:timeout maximumAge:maximumAge permission:nil position:completion];
+}
+@end

package/src/geolocation.macos.ts

@@ -1,8 +1,71 @@
-// Geolocation — AppKit host leaf. CoreLocation is not bridged on the dev host.
-import type { Capability, GeolocationImpl } from './types'
+// Package-owned Core Location facade, loaded by the existing macOS native graph.
+import type { Capability, GeolocationImpl, GeolocationPosition, PermissionResult } from './types'
+
+declare const XplatGeolocation: {
+	isAvailable(): boolean
+	ensure(completion: (result: PermissionResult) => void): void
+	positionTimeoutMaximumAgeCompletion(
+		highAccuracy: boolean,
+		timeout: number,
+		maximumAge: number,
+		completion: (positionJSON: string | null, code: number, message: string) => void,
+	): void
+}
+
+const available = () => typeof XplatGeolocation !== 'undefined' && XplatGeolocation.isAvailable()
+
+const milliseconds = (value: number | undefined, fallback: number) =>
+	value === undefined || Number.isNaN(value) ? fallback : Math.max(0, value)
+
+const impl: GeolocationImpl = {
+	getCurrentPosition(options) {
+		return new Promise((resolve, reject) => {
+			if (!available()) {
+				reject(Object.assign(new Error('Location host unavailable'), { code: 2 }))
+
+				return
+			}
+
+			const timeout = milliseconds(options?.timeout, Infinity)
+			XplatGeolocation.positionTimeoutMaximumAgeCompletion(
+				options?.enableHighAccuracy ?? false,
+				timeout === Infinity ? -1 : timeout,
+				milliseconds(options?.maximumAge, 0),
+				(positionJSON, code, message) => {
+					if (code === 0 && positionJSON) {
+						try {
+							resolve(JSON.parse(positionJSON) as GeolocationPosition)
+						} catch (error) {
+							reject(error)
+						}
+					} else {
+						reject(
+							Object.assign(new Error(message || 'Location unavailable'), {
+								code: code || 2,
+							}),
+						)
+					}
+				},
+			)
+		})
+	},
+}
 
 export const geolocation: Capability<GeolocationImpl> = {
-	supported: false,
-	ensure: async () => 'unsupported',
-	impl: null,
+	get supported() {
+		return available()
+	},
+	async ensure() {
+		if (!available()) {
+			return 'unsupported'
+		}
+
+		return new Promise<PermissionResult>((resolve) => XplatGeolocation.ensure(resolve))
+	},
+	get impl() {
+		return available() ? impl : null
+	},
 }
+
+const permissionOwners = ((globalThis as any).__xplatPermissionOwners ??= {})
+permissionOwners.location = () => geolocation.ensure()

package/src/geolocation.ts

@@ -5,13 +5,21 @@ import { CoreTypes } from '@nativescript/core'
 import type { Capability, GeolocationImpl, GeolocationPosition } from './types'
 
 function asPosition(nativeLocation: any): GeolocationPosition {
+	const android = nativeLocation.android
+	const ios = nativeLocation.ios
+	const heading = nativeLocation.direction ?? nativeLocation.heading
+	const speed = nativeLocation.speed
 	return {
 		latitude: nativeLocation.latitude,
 		longitude: nativeLocation.longitude,
-		accuracy: nativeLocation.horizontalAccuracy ?? nativeLocation.accuracy ?? 0,
-		altitude: nativeLocation.altitude ?? null,
-		heading: nativeLocation.direction ?? nativeLocation.heading ?? null,
-		speed: nativeLocation.speed ?? null,
+		accuracy: Math.max(0, nativeLocation.horizontalAccuracy ?? nativeLocation.accuracy ?? 0),
+		// Altitude itself can be negative; iOS validity uses verticalAccuracy.
+		altitude:
+			(android && !android.hasAltitude()) || (ios && ios.verticalAccuracy < 0)
+				? null
+				: (nativeLocation.altitude ?? null),
+		heading: (android && !android.hasBearing()) || heading == null || heading < 0 ? null : heading,
+		speed: (android && !android.hasSpeed()) || speed == null || speed < 0 ? null : speed,
 		timestamp: Number(nativeLocation.timestamp ?? Date.now()),
 	}
 }

package/src/geolocation.web.ts

@@ -43,7 +43,32 @@ export const geolocation: Capability<GeolocationImpl> = {
 			return 'granted'
 		} catch (error) {
 			const code = (error as { code?: number }).code
-			return code === 1 ? 'denied' : 'unsupported'
+			if (code === 1) {
+				return 'denied'
+			}
+
+			if (code === 3) {
+				return 'granted'
+			}
+
+			// POSITION_UNAVAILABLE can precede authorization (inactive document).
+			// Only a permission query can establish access in that case.
+			if (code === 2 && navigator.permissions?.query) {
+				try {
+					const permission = await navigator.permissions.query({ name: 'geolocation' })
+					if (permission.state === 'granted') {
+						return 'granted'
+					}
+
+					if (permission.state === 'denied') {
+						return 'denied'
+					}
+				} catch {
+					// Some browsers expose Permissions but cannot query geolocation.
+				}
+			}
+
+			return 'unsupported'
 		}
 	},
 	impl,

package/src/geolocation.windows.ts

@@ -0,0 +1,9 @@
+// Windows leaf — @nativescript/geolocation ships no windows entry, so the
+// capability reports unsupported rather than breaking the import graph.
+import type { Capability, GeolocationImpl } from './types'
+
+export const geolocation: Capability<GeolocationImpl> = {
+	supported: false,
+	ensure: async () => 'unsupported',
+	impl: null,
+}

package/types/generated/.tsrx-typegen-manifest.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "files": [
+    "geolocation.d.ts",
+    "geolocation.macos.d.ts",
+    "geolocation.web.d.ts",
+    "geolocation.windows.d.ts",
+    "index.d.ts",
+    "index.macos.d.ts",
+    "types.d.ts"
+  ]
+}

package/types/generated/geolocation.d.ts

@@ -0,0 +1,2 @@
+import type { Capability, GeolocationImpl } from './types.js';
+export declare const geolocation: Capability<GeolocationImpl>;

package/types/generated/geolocation.macos.d.ts

@@ -0,0 +1,2 @@
+import type { Capability, GeolocationImpl } from './types.js';
+export declare const geolocation: Capability<GeolocationImpl>;

package/types/generated/geolocation.web.d.ts

@@ -0,0 +1,2 @@
+import type { Capability, GeolocationImpl } from './types.js';
+export declare const geolocation: Capability<GeolocationImpl>;

package/types/generated/geolocation.windows.d.ts

@@ -0,0 +1,2 @@
+import type { Capability, GeolocationImpl } from './types.js';
+export declare const geolocation: Capability<GeolocationImpl>;

package/types/generated/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export { geolocation } from './geolocation.js';

package/types/generated/index.macos.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export { geolocation } from './geolocation.macos.js';

package/types/generated/types.d.ts

@@ -0,0 +1,25 @@
+/** Optional capability — never throws for absence (docs/platform/platform-services.md). */
+export interface Capability<T> {
+    supported: boolean;
+    ensure(): Promise<'granted' | 'denied' | 'unsupported'>;
+    /** usable iff supported && ensured */
+    impl: T | null;
+}
+export type PermissionResult = 'granted' | 'denied' | 'unsupported';
+export interface GeolocationOptions {
+    enableHighAccuracy?: boolean;
+    timeout?: number;
+    maximumAge?: number;
+}
+export interface GeolocationPosition {
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+    altitude: number | null;
+    heading: number | null;
+    speed: number | null;
+    timestamp: number;
+}
+export interface GeolocationImpl {
+    getCurrentPosition(options?: GeolocationOptions): Promise<GeolocationPosition>;
+}