@octane-xplat/platform 0.1.0 → 0.4.0

package/README.md

@@ -0,0 +1,37 @@
+# @octane-xplat/platform
+
+> Headless platform capabilities for Octane xplat — one shared API surface,
+> resolved per target (`*.web` under web conditions, `*.native`/`.ios`/
+> `.android` under native).
+>
+> Status: `0.x` — the API surface is still moving.
+
+```sh
+pnpm add @octane-xplat/platform octane
+```
+
+`octane` is a required peer; the `@nativescript/*` peers are optional and
+only needed for native targets.
+
+```ts
+import { storage, permissions } from '@octane-xplat/platform'
+
+storage.setString('has-seen-welcome', 'true')
+const seen = storage.getString('has-seen-welcome')
+
+const result = await permissions.ensure('camera')
+```
+
+Services cover storage, permissions, share, haptics, media picking, deep
+links, and more. The full capability map lives in the docs:
+
+- [Using device features](https://octane-xplat.goddardai.org/platform-services) — guide
+- [Platform-service notes](https://octane-xplat.goddardai.org/notes/platform-notes) — per-capability impl map
+
+Rules for consumers:
+
+- Import from the package (`'@octane-xplat/platform'` or a submodule like
+  `'@octane-xplat/platform/storage'`) — never a leaf impl file.
+- Optional capabilities return `{ supported: boolean }` rather than throwing.
+- This package is headless only. UI-shaped plugins (drawer, menu) are leaf
+  primitives in [`@octane-xplat/ui`](https://octane-xplat.goddardai.org/primitives).

package/package.json

@@ -1,32 +1,45 @@
 {
   "name": "@octane-xplat/platform",
-  "version": "0.1.0",
+  "version": "0.4.0",
+  "description": "Headless platform capabilities for Octane xplat — web + NativeScript leaf pairs",
+  "files": [
+    "src"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
     "./*": "./src/*"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@nativescript/biometrics": "1.3.1",
+    "@nativescript/geolocation": "9.0.0",
     "@nativescript/haptics": "3.1.0",
     "@nativescript/imagepicker": "5.0.0",
     "@nativescript/local-notifications": "7.0.0",
+    "@nativescript-community/ui-document-picker": "1.1.29",
     "@nativescript/secure-storage": "4.0.2",
     "@nativescript/social-share": "2.3.0",
     "nativescript-clipboard": "2.1.1"
   },
   "devDependencies": {
+    "@nativescript-community/octane": "0.2.1",
     "@nativescript/core": "9.1.2",
-    "octane": "0.4.0"
+    "octane": "0.5.0"
   },
   "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
     "octane": ">=0.1.51 <1"
   },
-  "description": "Headless platform capabilities for Octane xplat — web + NativeScript leaf pairs",
-  "files": [
-    "src"
-  ],
-  "publishConfig": {
-    "access": "public"
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
   }
 }

package/src/a11y.native.ts

@@ -1,14 +1,18 @@
 // A11y announce — native leaf. UIAccessibility announcement notification on
 // iOS; View.announceForAccessibility on Android (posted on the content view).
-import { Application } from '@nativescript/core';
+import { Application } from '@nativescript/core'
 
 export function announce(text: string): void {
 	if (Application.ios) {
-		UIAccessibilityPostNotification(UIAccessibilityAnnouncementNotification, text);
-		return;
+		UIAccessibilityPostNotification(UIAccessibilityAnnouncementNotification, text)
+		return
 	}
+
 	if (Application.android) {
-		const view = Application.android.foregroundActivity?.findViewById?.(16908290 /* android.R.id.content */);
-		view?.announceForAccessibility?.(text);
+		const view = Application.android.foregroundActivity?.findViewById?.(
+			16908290 /* android.R.id.content */,
+		)
+
+		view?.announceForAccessibility?.(text)
 	}
 }

package/src/a11y.web.ts

@@ -1,19 +1,23 @@
 // A11y announce — web leaf. A polite aria-live region receives the text;
 // screen readers speak the DOM mutation.
-let region: HTMLElement | null = null;
+let region: HTMLElement | null = null
 
 export function announce(text: string): void {
 	if (!region) {
-		region = document.createElement('div');
-		region.setAttribute('aria-live', 'polite');
-		region.setAttribute('role', 'status');
+		region = document.createElement('div')
+		region.setAttribute('aria-live', 'polite')
+		region.setAttribute('role', 'status')
 		region.style.cssText =
-			'position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);';
-		document.body.appendChild(region);
+			'position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);'
+
+		document.body.appendChild(region)
 	}
-	region.textContent = '';
+
+	region.textContent = ''
 	// Two writes in one frame collapse — force the SR to see a change.
 	requestAnimationFrame(() => {
-		if (region) region.textContent = text;
-	});
+		if (region) {
+			region.textContent = text
+		}
+	})
 }

package/src/app-info.native.ts

@@ -0,0 +1,35 @@
+// App info — native leaf. Read the values from the installed app bundle.
+import { Application } from '@nativescript/core'
+import type { AppInfo } from './types'
+
+function value(value: unknown): string | null {
+	return value === undefined || value === null ? null : String(value)
+}
+
+function read(): AppInfo {
+	if (Application.android) {
+		const context = Application.android.context
+		const packageId = context.getPackageName()
+		const packageInfo = context.getPackageManager().getPackageInfo(packageId, 0)
+		return {
+			supported: true,
+			version: value(packageInfo.versionName),
+			build: value(packageInfo.versionCode),
+			bundleId: packageId,
+		}
+	}
+
+	if (Application.ios) {
+		const bundle = NSBundle.mainBundle
+		return {
+			supported: true,
+			version: value(bundle.objectForInfoDictionaryKey('CFBundleShortVersionString')),
+			build: value(bundle.objectForInfoDictionaryKey('CFBundleVersion')),
+			bundleId: value(bundle.bundleIdentifier),
+		}
+	}
+
+	return { supported: false, version: null, build: null, bundleId: null }
+}
+
+export const appInfo = read()

package/src/app-info.web.ts

@@ -0,0 +1,10 @@
+// App info — web leaf. A browser bundle has no trustworthy native version,
+// build, or bundle identifier, so the contract reports that honestly.
+import type { AppInfo } from './types'
+
+export const appInfo: AppInfo = {
+	supported: false,
+	version: null,
+	build: null,
+	bundleId: null,
+}

package/src/biometrics.native.ts

@@ -1,24 +1,24 @@
 // Biometrics — FaceID/TouchID/fingerprint via @nativescript/biometrics.
-import { BiometricAuth } from '@nativescript/biometrics';
-import type { Capability } from './types';
-import type { BiometricsImpl } from './types';
+import { BiometricAuth } from '@nativescript/biometrics'
+import type { Capability } from './types'
+import type { BiometricsImpl } from './types'
 
-const bio = new BiometricAuth();
+const bio = new BiometricAuth()
 
 export const biometrics: Capability<BiometricsImpl> = {
 	supported: true,
 	async ensure() {
-		const r = await bio.available();
-		return r.any ? 'granted' : 'unsupported';
+		const r = await bio.available()
+		return r.any ? 'granted' : 'unsupported'
 	},
 	impl: {
 		async verify(reason) {
 			try {
-				const r = await bio.verifyBiometric({ title: reason });
-				return r.code === 0;
+				const r = await bio.verifyBiometric({ title: reason })
+				return r.code === 0
 			} catch {
-				return false;
+				return false
 			}
 		},
 	},
-};
+}

package/src/biometrics.web.ts

@@ -1,21 +1,13 @@
-// Biometrics — web leaf. Platform authenticator presence is the honest
-// signal; an actual WebAuthn ceremony is an auth-flow concern, not this seam.
-import type { BiometricsImpl, Capability } from './types';
-
-const pkc = () => (globalThis as any).PublicKeyCredential;
+// Biometrics — web leaf. WebAuthn is an authentication ceremony, not a
+// standalone local-presence API: it requires an RP challenge and a registered
+// credential, and may require a user gesture. Do not claim it implements the
+// native verify(reason) contract by creating an ephemeral passkey.
+import type { BiometricsImpl, Capability } from './types'
 
 export const biometrics: Capability<BiometricsImpl> = {
-	supported: typeof pkc() !== 'undefined',
+	supported: false,
 	async ensure() {
-		if (!pkc()) return 'unsupported';
-		const ok = await pkc().isUserVerifyingPlatformAuthenticatorAvailable();
-		return ok ? 'granted' : 'unsupported';
-	},
-	impl: {
-		// A bare verify() has no ceremony target — WebAuthn needs a challenge.
-		// Report presence; wire real attestation when an auth flow exists.
-		async verify(_reason: string) {
-			return false;
-		},
+		return 'unsupported'
 	},
-};
+	impl: null,
+}

package/src/clipboard.native.ts

@@ -1,17 +1,30 @@
-// Clipboard — pasteboard via nativescript-clipboard (sync API wrapped async
-// to keep the shared contract awaitable on both sides).
-import { getTextSync, setTextSync } from 'nativescript-clipboard';
+// Core provides native clipboard writes. The plugin remains for reading text,
+// which Core does not expose.
+import { Utils } from '@nativescript/core'
+import { getTextSync } from 'nativescript-clipboard'
+
+async function writeText(text: string): Promise<boolean> {
+	try {
+		Utils.copyToClipboard(text)
+		return true
+	} catch {
+		return false
+	}
+}
+
+async function readText(): Promise<string | null> {
+	try {
+		return getTextSync()
+	} catch {
+		return null
+	}
+}
 
 export const clipboard = {
-	async write(text: string): Promise<boolean> {
-		setTextSync(text);
-		return true;
-	},
-	async read(): Promise<string | null> {
-		try {
-			return getTextSync();
-		} catch {
-			return null;
-		}
-	},
-};
+	canCopy: true,
+	writeText,
+	readText,
+	// Keep the original names available for existing consumers.
+	write: writeText,
+	read: readText,
+}

package/src/clipboard.web.ts

@@ -1,18 +1,30 @@
-// Clipboard — async permission-gated on web; read may be denied silently.
+// Clipboard — browser support is feature-detected; writes can still be denied
+// by browser policy or permission state.
+const canCopy =
+	typeof navigator !== 'undefined' && typeof navigator.clipboard?.writeText === 'function'
+
+async function writeText(text: string): Promise<boolean> {
+	try {
+		await navigator.clipboard.writeText(text)
+		return true
+	} catch {
+		return false
+	}
+}
+
+async function readText(): Promise<string | null> {
+	try {
+		return await navigator.clipboard.readText()
+	} catch {
+		return null
+	}
+}
+
 export const clipboard = {
-	async write(text: string): Promise<boolean> {
-		try {
-			await navigator.clipboard.writeText(text);
-			return true;
-		} catch {
-			return false;
-		}
-	},
-	async read(): Promise<string | null> {
-		try {
-			return await navigator.clipboard.readText();
-		} catch {
-			return null;
-		}
-	},
-};
+	canCopy,
+	writeText,
+	readText,
+	// Keep the original names available for existing consumers.
+	write: writeText,
+	read: readText,
+}

package/src/connectivity.native.ts

@@ -0,0 +1,86 @@
+// Connectivity — native leaf. NativeScript exposes this through @nativescript/core;
+// it is a built-in service rather than a separate @nativescript/connectivity plugin.
+import { Connectivity } from '@nativescript/core'
+import type { ConnectionType, ConnectivityImpl, ConnectivityState } from './types'
+
+const listeners = new Set<(state: ConnectivityState) => void>()
+let monitoring = false
+
+function connectionType(value = Connectivity.getConnectionType()): ConnectionType {
+	const types = Connectivity.connectionType as any
+	if (value === types.none) {
+		return 'none'
+	}
+
+	if (value === types.wifi) {
+		return 'wifi'
+	}
+
+	if (value === types.mobile) {
+		return 'mobile'
+	}
+
+	if (value === types.ethernet) {
+		return 'ethernet'
+	}
+
+	if (value === types.bluetooth) {
+		return 'bluetooth'
+	}
+
+	if (value === types.vpn) {
+		return 'vpn'
+	}
+
+	return 'unknown'
+}
+
+function read(): ConnectivityState {
+	const type = connectionType()
+	return { online: type !== 'none', type }
+}
+
+function notify(value: number) {
+	if (listeners.size === 0) {
+		return
+	}
+
+	const type = connectionType(value)
+	const state = { online: type !== 'none', type }
+	for (const listener of listeners) {
+		listener(state)
+	}
+}
+
+function startMonitoring() {
+	if (monitoring) {
+		return
+	}
+
+	Connectivity.startMonitoring(notify)
+	monitoring = true
+}
+
+function stopMonitoring() {
+	if (!monitoring) {
+		return
+	}
+
+	Connectivity.stopMonitoring()
+	monitoring = false
+}
+
+export const connectivity: ConnectivityImpl = {
+	getState: read,
+	subscribe(listener) {
+		listeners.add(listener)
+		listener(read())
+		startMonitoring()
+		return () => {
+			listeners.delete(listener)
+			if (listeners.size === 0) {
+				stopMonitoring()
+			}
+		}
+	},
+}

package/src/connectivity.web.ts

@@ -0,0 +1,62 @@
+// Connectivity — web leaf. Online state comes from navigator.onLine and
+// changes are delivered through the browser's online/offline events.
+import type { ConnectionType, ConnectivityImpl, ConnectivityState } from './types'
+
+const listeners = new Set<(state: ConnectivityState) => void>()
+
+function connectionType(): ConnectionType {
+	const type = (navigator as Navigator & { connection?: { type?: string } }).connection?.type
+	switch (type) {
+		case 'wifi':
+			return 'wifi'
+		case 'cellular':
+			return 'mobile'
+		case 'ethernet':
+			return 'ethernet'
+		case 'bluetooth':
+			return 'bluetooth'
+		case 'vpn':
+			return 'vpn'
+		default:
+			return navigator.onLine ? 'unknown' : 'none'
+	}
+}
+
+function read(): ConnectivityState {
+	return { online: navigator.onLine, type: connectionType() }
+}
+
+function notify() {
+	const state = read()
+	for (const listener of listeners) {
+		listener(state)
+	}
+}
+
+function addListeners() {
+	window.addEventListener('online', notify)
+	window.addEventListener('offline', notify)
+}
+
+function removeListeners() {
+	window.removeEventListener('online', notify)
+	window.removeEventListener('offline', notify)
+}
+
+export const connectivity: ConnectivityImpl = {
+	getState: read,
+	subscribe(listener) {
+		if (listeners.size === 0) {
+			addListeners()
+		}
+
+		listeners.add(listener)
+		listener(read())
+		return () => {
+			listeners.delete(listener)
+			if (listeners.size === 0) {
+				removeListeners()
+			}
+		}
+	},
+}

package/src/deep-links.native.ts

@@ -1,39 +1,66 @@
 // Deep links — native leaf. iOS delivers openUrl + launchOptions; Android
 // delivers an intent on resume/newIntent. Handlers get the raw URL string —
 // the app maps it onto its route table.
-import { Application } from '@nativescript/core';
+import { Application } from '@nativescript/core'
 
-type LinkHandler = (url: string) => void;
-const handlers = new Set<LinkHandler>();
-let wired = false;
-let initial: string | null = null;
+type LinkHandler = (url: string) => void
+const handlers = new Set<LinkHandler>()
+let wired = false
+let initial: string | null = null
+let lastUrl: string | null = null
+
+function dispatch(url: string | null | undefined) {
+	if (!url || url === lastUrl) {
+		return
+	}
+
+	lastUrl = url
+	for (const handler of handlers) {
+		handler(url)
+	}
+}
 
 function wire() {
-	if (wired) return;
-	wired = true;
+	if (wired) {
+		return
+	}
+
+	wired = true
+	Application.on(Application.launchEvent, (args: any) => {
+		const androidUrl = args.android?.getDataString?.()
+		const iosUrl = args.ios?.objectForKey?.('UIApplicationLaunchOptionsURLKey')?.absoluteString
+		initial = androidUrl || iosUrl || initial
+		dispatch(initial)
+	})
+
 	if (Application.ios) {
 		Application.on('openUrl', (args: any) => {
-			const url = args.url?.absoluteString ?? String(args.url ?? '');
-			for (const h of handlers) h(url);
-		});
+			const url = args.url?.absoluteString ?? String(args.url ?? '')
+			dispatch(url)
+		})
+
+		Application.on('continueActivity', (args: any) => {
+			dispatch(args.activity?.webpageURL?.absoluteString)
+		})
 	}
+
 	if (Application.android) {
 		Application.on(Application.resumeEvent, () => {
-			const intent = Application.android.foregroundActivity?.getIntent?.();
-			const url = intent?.getDataString?.();
-			if (url) for (const h of handlers) h(url);
-		});
+			const intent = Application.android.foregroundActivity?.getIntent?.()
+			const url = intent?.getDataString?.()
+			dispatch(url)
+		})
 	}
 }
 
 export function onDeepLink(cb: LinkHandler): () => void {
-	wire();
-	handlers.add(cb);
-	return () => handlers.delete(cb);
+	wire()
+	handlers.add(cb)
+	return () => handlers.delete(cb)
 }
 
 export function consumeInitialUrl(): string | null {
-	const u = initial;
-	initial = null;
-	return u;
+	const u = initial
+	initial = null
+	return u
 }

package/src/deep-links.web.ts

@@ -1,23 +1,28 @@
 // Deep links — web leaf. The URL IS the link: consumeInitialUrl returns the
 // current path; onDeepLink listens for popstate (back/forward = link events).
-type LinkHandler = (url: string) => void;
-const handlers = new Set<LinkHandler>();
-let wired = false;
+type LinkHandler = (url: string) => void
+const handlers = new Set<LinkHandler>()
+let wired = false
 
 function wire() {
-	if (wired) return;
-	wired = true;
+	if (wired) {
+		return
+	}
+
+	wired = true
 	window.addEventListener('popstate', () => {
-		for (const h of handlers) h(location.pathname + location.search);
-	});
+		for (const h of handlers) {
+			h(location.pathname + location.search)
+		}
+	})
 }
 
 export function onDeepLink(cb: LinkHandler): () => void {
-	wire();
-	handlers.add(cb);
-	return () => handlers.delete(cb);
+	wire()
+	handlers.add(cb)
+	return () => handlers.delete(cb)
 }
 
 export function consumeInitialUrl(): string | null {
-	return location.pathname === '/' ? null : location.pathname + location.search;
+	return location.pathname === '/' ? null : location.pathname + location.search
 }

package/src/device.native.ts

@@ -1,5 +1,5 @@
-import { Device } from '@nativescript/core';
-import type { DeviceInfo } from './types';
+import { Device } from '@nativescript/core'
+import type { DeviceInfo } from './types'
 
 export const device: DeviceInfo = {
 	os: Device.os.toLowerCase() === 'ios' ? 'ios' : 'android',
@@ -8,4 +8,4 @@ export const device: DeviceInfo = {
 	manufacturer: Device.manufacturer,
 	language: Device.language.split('-')[0] ?? '',
 	region: Device.region,
-};
+}

package/src/device.web.ts

@@ -1,7 +1,8 @@
-import type { DeviceInfo } from './types';
+import type { DeviceInfo } from './types'
 
-const ua = navigator.userAgent;
-const osVersion = ua.match(/(?:Mac OS X|Windows NT|Android|OS) ([\d._]+)/)?.[1]?.replace(/_/g, '.') ?? '';
+const ua = navigator.userAgent
+const osVersion =
+	ua.match(/(?:Mac OS X|Windows NT|Android|OS) ([\d._]+)/)?.[1]?.replace(/_/g, '.') ?? ''
 
 export const device: DeviceInfo = {
 	os: 'web',
@@ -10,4 +11,4 @@ export const device: DeviceInfo = {
 	manufacturer: '',
 	language: navigator.language.split('-')[0] ?? '',
 	region: navigator.language.split('-')[1] ?? '',
-};
+}