@livx.cc/appwrap 0.23.2 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.23.2",
+  "version": "0.25.0",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",

package/runtime/App_Resources/Android/src/main/res/xml/file_paths.xml

@@ -1,5 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- Paths FileProvider may expose. kit.share.files writes into cacheDir/shared. -->
+<!-- Paths FileProvider may expose.
+     - cacheDir/shared: kit.share.files staging area (keep exact, share writes here).
+     - The three roots below back kit.fs.getUri() so content:// resolves for every FsDirectory:
+       cache→getCacheDir, data→getFilesDir, documents→getExternalFilesDir(null). -->
 <paths>
     <cache-path name="shared" path="shared/" />
+    <cache-path name="fs_cache" path="." />
+    <files-path name="fs_data" path="." />
+    <external-files-path name="fs_documents" path="." />
 </paths>

package/runtime/app/main-page.ts

@@ -6,6 +6,8 @@ import { registerParityHandlers } from './shell/handlers-parity';
 import { registerSystemHandlers } from './shell/handlers-system';
 import { registerBillingHandlers } from './shell/handlers-billing';
 import { registerMediaHandlers } from './shell/handlers-media';
+import { registerKeyboardHandlers } from './shell/keyboard';
+import { registerFsHandlers } from './shell/handlers-fs';
 import { registerPushHandlers } from './shell/handlers-push';
 import { registerAndroidHandlers } from './shell/handlers-android';
 import { registerOptionalHandlers } from './shell/optional-handlers.generated';
@@ -41,6 +43,8 @@ export function onPageLoaded(args: EventData): void {
   registerSystemHandlers();
   registerBillingHandlers();
   registerMediaHandlers();
+  registerKeyboardHandlers();
+  registerFsHandlers();
   registerPushHandlers();
   // Last on purpose: overrides the iOS-only placeholders with Android impls
   if (isAndroid) registerAndroidHandlers();

package/runtime/app/shell/capabilities.manifest.ts

@@ -68,13 +68,18 @@ export const MODULES: ModuleManifest[] = [
   { name: 'haptics', core: true, group: 'core', capabilities: { haptics: 'native' } },
   { name: 'share', core: true, group: 'core', capabilities: { share: 'native', shareFiles: 'native' } },
   { name: 'storage', core: true, group: 'core', capabilities: { storage: 'native', secureStorage: 'native' } },
+  // fs: app-sandbox file I/O (documents/data/cache) + system document picker. Core — every root is
+  // inside the app sandbox and the picker returns user-chosen security-scoped URIs → zero perms.
+  { name: 'fs', core: true, group: 'core', capabilities: { fs: 'native' } },
   { name: 'toast', core: true, group: 'core', capabilities: { toast: 'native', banner: 'native', updates: 'native' } },
   { name: 'statusBar', core: true, group: 'core', capabilities: { statusBar: 'native', themeColor: 'native' } },
   { name: 'device', core: true, group: 'extended', capabilities: { device: 'native' } },
   { name: 'clipboard', core: true, group: 'extended', capabilities: { clipboard: 'native' } },
   { name: 'network', core: true, group: 'extended', capabilities: { network: 'native' } },
-  { name: 'screen', core: true, group: 'extended', capabilities: { screen: 'native', dialogs: 'native', orientation: 'native' } },
-  { name: 'app', core: true, group: 'system', capabilities: { app: 'native', browser: 'native' } },
+  { name: 'screen', core: true, group: 'extended', capabilities: { screen: 'native', dialogs: 'native', orientation: 'native', keyboard: 'native' } },
+  // badge: app-icon badge via the always-bundled notifications.setBadge handler — iOS sets the
+  // springboard badge; Android is an honest no-op (launchers own badges) → ios:true / android:false.
+  { name: 'app', core: true, group: 'system', capabilities: { app: 'native', browser: 'native', badge: { ios: true, android: false } } },
 
   // ── opt-in: permission / dependency / weight-bearing ───────────────────
   // POST_NOTIFICATIONS / VIBRATE / USE_BIOMETRIC etc. are in the template's baseline manifest already.
@@ -118,6 +123,7 @@ export const MODULES: ModuleManifest[] = [
   {
     name: 'contacts', group: 'parity',
     capabilities: { contacts: 'native' },
+    ios: { permissions: [{ key: 'NSContactsUsageDescription', domain: 'contacts', defaultUsage: 'Find which of your contacts already play, and invite the rest.' }] },
     android: { permissions: ['android.permission.READ_CONTACTS'] },
   },
   {
@@ -129,23 +135,69 @@ export const MODULES: ModuleManifest[] = [
     ] },
     android: { permissions: ['android.permission.READ_CALENDAR', 'android.permission.WRITE_CALENDAR'] },
   },
-  {
-    name: 'reviews', group: 'system',
-    capabilities: { reviews: { ios: true, android: false } },
-  },
   {
     name: 'billing', group: 'billing',
     capabilities: { billing: { ios: true, android: false } },
   },
 
-  // ── oauth — system-browser OAuth (iOS ASWebAuthenticationSession) ──
-  // Opt-in, strippable (own handler file). No permissions/entitlements — ASWebAuthenticationSession
-  // needs none; it only relies on the app's urlScheme so the provider redirect returns to the app.
+  // ── reviews — in-app store review prompt — opt-in, STRIPPABLE (own handler + group) ──
+  // Moved out of the always-bundled parity/system handlers: the Android Play In-App Review path
+  // references `com.google.android.play:review` classes — a gradle dep that must NOT land in builds
+  // without `reviews` (missing-class crash / dead weight). iOS: SKStoreReviewController (no dep).
+  // HONEST LIMIT (Android): the dialog only surfaces for a Play-Store-track install; on a bare
+  // emulator / sideload the API resolves WITHOUT showing UI (documented; same class as billing).
+  {
+    name: 'reviews', group: 'reviews',
+    capabilities: { reviews: { ios: true, android: true } },
+    android: { gradleDeps: ['com.google.android.play:review:2.0.2'] },
+  },
+
+  // ── oauth — system-browser OAuth (iOS ASWebAuthenticationSession / Android Chrome Custom Tabs) ──
+  // Opt-in, strippable (own handler file). iOS: ASWebAuthenticationSession (auto-closes on redirect).
+  // Android: a Chrome Custom Tab — it does NOT auto-close on the provider redirect, so the callback
+  // (`callbackScheme://…`) returns via the app's EXISTING urlScheme deep-link path; the handler hooks
+  // that delivery, matches the scheme, and resolves. androidx.browser is already a baseline dep
+  // (browser.open); declared here too so the module stays self-contained (CLI dedups). No permission.
   // Lets Google et al. complete sign-in they reject inside an embedded WebView (disallowed_useragent).
-  // Android (Custom Tabs + intent callback) is a future addition.
   {
     name: 'oauth', group: 'oauth',
-    capabilities: { oauth: { ios: true, android: false } },
+    capabilities: { oauth: { ios: true, android: true } },
+    android: { gradleDeps: ['androidx.browser:browser:1.8.0'] },
+  },
+
+  // ── scanner — camera barcode/QR decode — opt-in (camera permission + decoder weight) ──
+  // Reuses the SAME camera permission as media/camera (the CLI dedups across active modules), so a
+  // scanner-only app still gets NSCameraUsageDescription / CAMERA without a second permission.
+  // iOS: AVCaptureMetadataOutput (no extra dep). Android: ZXing-android-embedded — it ships its own
+  // capture Activity, so the handler just launches it via startActivityForResult and reads the
+  // result (fewest moving parts vs ML Kit, which needs a hand-built Camera2/CameraX preview).
+  {
+    name: 'scanner', group: 'scanner',
+    capabilities: { scanner: 'native' },
+    ios: { permissions: [{ key: 'NSCameraUsageDescription', domain: 'camera', defaultUsage: 'Scan barcodes and QR codes with the camera.' }] },
+    android: {
+      permissions: ['android.permission.CAMERA'],
+      gradleDeps: ['com.journeyapps:zxing-android-embedded:4.3.0'],
+    },
+  },
+
+  // ── speech (TTS + STT) — opt-in module; ONE coherent kit.speech, TWO honest capabilities ──
+  // ONE module (not split TTS-core / STT-opt-in): TTS-only apps are rare and a split fractures
+  // `kit.speech` across tiers. The module declares the STT perms (mic + speech-recognition); the
+  // CLI only stamps them when `speech` is active, and TTS (`speak`/`voices`) rides along perm-free.
+  // It advertises TWO handshake caps so the kit gates each concern honestly:
+  //   `speech`            → TTS (synthesis), always native on a shell.
+  //   `speechRecognition` → STT (transcription), always native on a shell.
+  // iOS: AVSpeechSynthesizer (TTS, no dep) + SFSpeechRecognizer/AVAudioEngine (STT). Android:
+  // TextToSpeech + SpeechRecognizer — both plain Java → NO kotlin flag, NO gradle dep.
+  {
+    name: 'speech', group: 'speech',
+    capabilities: { speech: 'native', speechRecognition: 'native' },
+    ios: { permissions: [
+      { key: 'NSSpeechRecognitionUsageDescription', domain: 'speechRecognition', defaultUsage: 'Transcribe your speech to text.' },
+      { key: 'NSMicrophoneUsageDescription', domain: 'microphone', defaultUsage: 'Listen to your voice for speech-to-text.' },
+    ] },
+    android: { permissions: ['android.permission.RECORD_AUDIO'] },
   },
 
   // ── health (steps) — opt-in heavy module; FG live + BG via OS step store ──
@@ -198,7 +250,7 @@ export const MODULES: ModuleManifest[] = [
 
 /** Opt-in registration groups that own their own NS handler file (strippable when inactive). Core
  * groups (core/extended/parity/system/media/billing) are always bundled; only these are CLI-gated. */
-export const OPTIONAL_GROUPS = ['health', 'oauth'] as const;
+export const OPTIONAL_GROUPS = ['health', 'oauth', 'reviews', 'scanner', 'speech'] as const;
 
 /** Resolve the active capability map for the handshake from a set of active capability names. */
 export function buildCapabilityMap(

package/runtime/app/shell/config.ts

@@ -40,9 +40,18 @@ export const SHELL_CONFIG = {
    * fights the app:// handler / remote-update detection). On by default; set false to opt out and keep
    * the SW (e.g. for in-WebView web-push). See `serviceWorkerGuardJs`. */
   neutralizeServiceWorker: true,
+  /** Open external-origin navigations (`<a>` to another origin, incl. `target="_blank"`, and
+   * `window.open(...)`) in the OS default browser (Safari / Chrome) instead of inside the shell
+   * WebView — regular-native-app behavior. Same-origin SPA navigation is untouched. Off by default.
+   * See `externalNavGuardJs`. */
+  openNewWindowsInBrowser: false,
   /** Remote push configured, per platform (iOS aps-environment entitlement / Android FCM). Drives the
    * `push` capability flag at runtime by platform — off unless `appwrap.json.push` enables it, so an
    * un-provisioned build honestly reports 'none' (and a personal-team iOS build keeps `pushIos:false`). */
   pushIos: false,
   pushAndroid: false,
+  /** Optional backend URL that the shell POSTs the device token to NATIVELY as soon as it's acquired —
+   * `{ token, platform: 'ios'|'android' }`. Native HTTP avoids the WKWebView `app://` cross-origin/CORS
+   * wall, so a token reaches your server without any WebView fetch. Empty = the app handles sending. */
+  pushRegistrationUrl: '',
 };

package/runtime/app/shell/custom-webview.android.ts

@@ -1,7 +1,7 @@
 import { WebView, Utils, knownFolders, path as nsPath, File } from '@nativescript/core';
 import { SHELL_CONFIG } from './config';
 import { mimeFor } from './mime';
-import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs } from './web-quirks';
+import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs, externalNavGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
 import { requestPermissions } from './android-helpers';
 
@@ -27,7 +27,7 @@ const PROMPT_PREFIX = '__appwrap__:';
  * native-feel. Globals first so the page can read __APPWRAP__ / __APPWRAP_BACKEND_ORIGIN__ before its
  * own scripts run. Built lazily (not a const) so envGlobalsJs() detects against a live activity context. */
 function buildBootstrapJs(): string {
-  return `${envGlobalsJs()}\n${APPWRAP_GLOBALS_JS}\n${TRANSPORT_SHIM}\n${serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker)}\n${NATIVE_FEEL_JS}`;
+  return `${envGlobalsJs()}\n${APPWRAP_GLOBALS_JS}\n${TRANSPORT_SHIM}\n${serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker)}\n${externalNavGuardJs(SHELL_CONFIG.openNewWindowsInBrowser)}\n${NATIVE_FEEL_JS}`;
 }
 
 /**

package/runtime/app/shell/custom-webview.ios.ts

@@ -1,7 +1,7 @@
 import { WebView, knownFolders, path as nsPath, File } from '@nativescript/core';
 import { SHELL_CONFIG } from './config';
 import { mimeFor } from './mime';
-import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, mediaCaptureGuardJs, serviceWorkerGuardJs } from './web-quirks';
+import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, mediaCaptureGuardJs, serviceWorkerGuardJs, externalNavGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
 import { createUiDelegate } from './ios-ui-delegate';
 import { appwrapNativeLog } from './native-log';
@@ -56,7 +56,8 @@ export class CustomWebView extends WebView {
     const hasPlistKey = (k: string) => !!NSBundle.mainBundle.objectForInfoDictionaryKey(k);
     const mediaGuard = mediaCaptureGuardJs(hasPlistKey('NSCameraUsageDescription'), hasPlistKey('NSMicrophoneUsageDescription'));
     const swGuard = serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker);
-    for (const src of [envGlobalsJs(), APPWRAP_GLOBALS_JS, mediaGuard, swGuard, NATIVE_FEEL_JS]) {
+    const extNavGuard = externalNavGuardJs(SHELL_CONFIG.openNewWindowsInBrowser);
+    for (const src of [envGlobalsJs(), APPWRAP_GLOBALS_JS, mediaGuard, swGuard, extNavGuard, NATIVE_FEEL_JS]) {
       const script = WKUserScript.alloc().initWithSourceInjectionTimeForMainFrameOnly(
         src,
         WKUserScriptInjectionTime.AtDocumentStart,

package/runtime/app/shell/events.ts

@@ -10,8 +10,19 @@ let pendingPushTap: { data: Record<string, string> } | null = null;
 // (the cold-start-from-notification bug). So we gate delivery on the handshake.
 let pwaReady = false;
 
+/** A pending native-side consumer of an inbound deep link (e.g. the Android OAuth flow waiting for
+ * the provider's `callbackScheme://…` redirect). Returns true if it CONSUMED the URL — then it's an
+ * internal callback, not an app deep link, and must NOT reach the PWA. Set by handlers-oauth. */
+let deepLinkInterceptor: ((url: string) => boolean) | null = null;
+export function setDeepLinkInterceptor(fn: ((url: string) => boolean) | null): void {
+  deepLinkInterceptor = fn;
+}
+
 /** Called by the iOS delegate (cold start or while running) and Android intents. */
 export function onDeepLink(url: string): void {
+  // Give a native consumer (OAuth callback) first refusal — a matched OAuth redirect is internal
+  // plumbing, not an app deep link, so it's swallowed here and never forwarded to the PWA.
+  if (deepLinkInterceptor?.(url)) return;
   if (pwaReady) bridge.emit('deeplink.open', { url });
   else pendingDeepLink = url; // buffer until the PWA handshakes
 }

package/runtime/app/shell/handlers-android.ts

@@ -320,6 +320,49 @@ export function registerAndroidHandlers(): void {
     };
   });
 
+  // ── contacts bulk read (ContactsContract query over all contacts) ──
+  bridge.register('contacts.getAll', async () => {
+    if (!(await requestPermissions(['android.permission.READ_CONTACTS']))) {
+      throw err('DENIED', 'contacts permission denied');
+    }
+    const CC = android.provider.ContactsContract;
+    const cr = context().getContentResolver();
+    const column = (uri: any, col: string, sel: string | null, args: string[] | null): string[] => {
+      const out: string[] = [];
+      const cursor = cr.query(uri, [col], sel, args, null);
+      if (cursor) {
+        const idx = cursor.getColumnIndex(col);
+        while (cursor.moveToNext()) out.push(String(cursor.getString(idx)));
+        cursor.close();
+      }
+      return out;
+    };
+
+    const contacts: Array<{ name: string; phones: string[]; emails: string[] }> = [];
+    const cursor = cr.query(
+      CC.Contacts.CONTENT_URI,
+      [CC.Contacts._ID, CC.Contacts.DISPLAY_NAME],
+      null, null, null
+    );
+    if (cursor) {
+      const idIdx = cursor.getColumnIndex(CC.Contacts._ID);
+      const nameIdx = cursor.getColumnIndex(CC.Contacts.DISPLAY_NAME);
+      while (cursor.moveToNext()) {
+        const contactId = String(cursor.getString(idIdx));
+        const name = cursor.getString(nameIdx) ?? '';
+        contacts.push({
+          name,
+          phones: column(CC.CommonDataKinds.Phone.CONTENT_URI, CC.CommonDataKinds.Phone.NUMBER,
+            CC.CommonDataKinds.Phone.CONTACT_ID + ' = ?', [contactId]),
+          emails: column(CC.CommonDataKinds.Email.CONTENT_URI, CC.CommonDataKinds.Email.ADDRESS,
+            CC.CommonDataKinds.Email.CONTACT_ID + ' = ?', [contactId]),
+        });
+      }
+      cursor.close();
+    }
+    return { contacts };
+  });
+
   // ── calendar (CalendarContract direct insert) ──────────────────────
   bridge.register('calendar.createEvent', async ({ title, start, durationMin, notes }: any) => {
     if (!(await requestPermissions(['android.permission.WRITE_CALENDAR', 'android.permission.READ_CALENDAR']))) {

package/runtime/app/shell/handlers-extended.ts

@@ -127,7 +127,10 @@ export function registerExtendedHandlers(): void {
       Utils.dispatchToMainThread(() => {
         UNUserNotificationCenter.currentNotificationCenter().setBadgeCountWithCompletionHandler?.(
           count,
-          () => {}
+          // iOS silently ignores the badge unless notification authorization (incl. .badge) was granted —
+          // the completion's error is the ONLY signal, so DON'T swallow it (else the badge just never
+          // appears with no explanation). Resolve regardless (the JS call itself didn't fail).
+          (error: any) => { if (error) console.warn('[appwrap] setBadge ignored — notifications not authorized?', String(error)); }
         );
         resolve();
       });