@octane-xplat/geolocation 0.0.1 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# @octane-xplat/geolocation
+# `@octane-xplat/geolocation`
 
-Version 0.0.1 is a reservation stub so the automated release can publish this package name. It has no supported API. Use a later release for the implementation.
+```sh
+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).
+
+```ts
+import { geolocation } from '@octane-xplat/geolocation'
+
+if ((await geolocation.ensure()) === 'granted') {
+	const pos = await geolocation.impl!.getCurrentPosition()
+	// { latitude, longitude, accuracy, altitude, heading, speed, timestamp }
+}
+```
+
+The shared capability contract: `supported` reports whether an
+implementation exists on this target, `ensure()` resolves
+`'granted' | 'denied' | 'unsupported'` (it prompts where the platform
+defers the prompt), and `impl` is the service once usable. Nullable
+`altitude`/`heading`/`speed` mean the platform did not report them.
+
+```ts
+import { geolocation } from '@octane-xplat/geolocation'
+
+if ((await geolocation.ensure()) === 'granted') {
+	const pos = await geolocation.impl!.getCurrentPosition()
+	// { latitude, longitude, accuracy, altitude, heading, speed, timestamp }
+}
+```
+
+Guide: [Using device features](../../docs/platform/platform-services.md);
+per-target availability: [platform notes](../../docs/notes/platform-notes.md).
+Exercised by the harness `Services` screen
+([`packages/app/src/Services.tsrx`](../app/src/Services.tsrx)).

package/package.json

@@ -1,19 +1,68 @@
 {
   "name": "@octane-xplat/geolocation",
-  "version": "0.0.1",
+  "version": "0.10.0",
   "description": "Device geolocation for Octane xplat — matching web + NativeScript implementations",
+  "keywords": [
+    "android",
+    "cross-platform",
+    "geolocation",
+    "gps",
+    "ios",
+    "location",
+    "nativescript",
+    "octane",
+    "web",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/geolocation",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/octane-xplat/octane-xplat.git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
     "directory": "packages/geolocation"
   },
-  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/geolocation",
-  "main": "./index.js",
-  "types": "./index.d.ts",
   "files": [
-    "README.md",
-    "index.js",
-    "index.d.ts"
-  ]
-}
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": "./src/index.macos.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": "./src/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript/geolocation": "9.0.0"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.4",
+    "@nativescript/core": "9.1.2",
+    "octane": "0.6.3"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "octane": ">=0.6.3 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "nativescript": {
+    "platforms": {
+      "android": "9.1.0",
+      "ios": "9.1.0"
+    }
+  },
+  "scripts": {
+    "test:packed": "node tests/packed-consumer.mjs"
+  }
+}

package/src/geolocation.macos.ts

@@ -0,0 +1,8 @@
+// Geolocation — AppKit host leaf. CoreLocation is not bridged on the dev host.
+import type { Capability, GeolocationImpl } from './types'
+
+export const geolocation: Capability<GeolocationImpl> = {
+	supported: false,
+	ensure: async () => 'unsupported',
+	impl: null,
+}

package/src/geolocation.ts

@@ -0,0 +1,49 @@
+// Geolocation — native leaf. The plugin's enableLocationRequest() owns the
+// runtime prompt; getCurrentLocation() is normalized to the web position shape.
+import * as geolocationApi from '@nativescript/geolocation'
+import { CoreTypes } from '@nativescript/core'
+import type { Capability, GeolocationImpl, GeolocationPosition } from './types'
+
+function asPosition(nativeLocation: any): GeolocationPosition {
+	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,
+		timestamp: Number(nativeLocation.timestamp ?? Date.now()),
+	}
+}
+
+const impl: GeolocationImpl = {
+	async getCurrentPosition(options) {
+		const nativePosition = await geolocationApi.getCurrentLocation({
+			desiredAccuracy: options?.enableHighAccuracy
+				? CoreTypes.Accuracy.high
+				: CoreTypes.Accuracy.any,
+			maximumAge: options?.maximumAge,
+			timeout: options?.timeout,
+		})
+
+		return asPosition(nativePosition)
+	},
+}
+
+export const geolocation: Capability<GeolocationImpl> = {
+	supported: true,
+	async ensure() {
+		try {
+			await geolocationApi.enableLocationRequest()
+			return 'granted'
+		} catch {
+			return 'denied'
+		}
+	},
+	impl,
+}
+
+// See @octane-xplat/media for the pattern — registers the kind this leaf owns
+// for the platform permissions dispatcher.
+const permissionOwners = ((globalThis as any).__xplatPermissionOwners ??= {})
+permissionOwners.location = () => geolocation.ensure()

package/src/geolocation.web.ts

@@ -0,0 +1,53 @@
+// Geolocation — web leaf. The browser owns the permission prompt and returns
+// the platform-neutral position shape used by the service contract.
+import type { Capability, GeolocationImpl, GeolocationOptions, GeolocationPosition } from './types'
+
+const supported = typeof navigator !== 'undefined' && 'geolocation' in navigator
+
+function readPosition(options?: GeolocationOptions): Promise<GeolocationPosition> {
+	return new Promise((resolve, reject) => {
+		navigator.geolocation.getCurrentPosition(
+			(position) =>
+				resolve({
+					latitude: position.coords.latitude,
+					longitude: position.coords.longitude,
+					accuracy: position.coords.accuracy,
+					altitude: position.coords.altitude,
+					heading: position.coords.heading,
+					speed: position.coords.speed,
+					timestamp: position.timestamp,
+				}),
+			reject,
+			{
+				enableHighAccuracy: options?.enableHighAccuracy,
+				timeout: options?.timeout,
+				maximumAge: options?.maximumAge,
+			},
+		)
+	})
+}
+
+const impl: GeolocationImpl = {
+	getCurrentPosition: readPosition,
+}
+
+export const geolocation: Capability<GeolocationImpl> = {
+	supported,
+	async ensure() {
+		if (!supported) {
+			return 'unsupported'
+		}
+
+		try {
+			await readPosition({ timeout: 15000 })
+			return 'granted'
+		} catch (error) {
+			const code = (error as { code?: number }).code
+			return code === 1 ? 'denied' : 'unsupported'
+		}
+	},
+	impl,
+}
+
+const permissionOwners = ((globalThis as any).__xplatPermissionOwners ??= {})
+permissionOwners.location = () => geolocation.ensure()

package/src/index.macos.ts

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

package/src/index.ts

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

package/src/types.ts

@@ -0,0 +1,29 @@
+/** 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>
+}

package/index.d.ts

@@ -1 +0,0 @@
-export {}

package/index.js

@@ -1,2 +0,0 @@
-// Reservation stub; implementation will arrive in a later release.
-module.exports = {}