@livx.cc/native-kit 0.28.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.28.0",
+  "version": "0.31.0",
   "description": "Isomorphic native-capabilities kit for PWAs \u2014 same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",

package/src/core/NativeKit.ts

@@ -2,6 +2,7 @@ import { AppwrapAdapter } from './appwrap-adapter';
 import { WebAdapter } from './web-adapter';
 import { Capability, Handshake, InvokeOptions, KIT_PROTOCOL, KitError, NativeKitAdapter, Platform, Unsubscribe } from './types';
 import { AppModule } from '../modules/app';
+import { BackgroundTaskModule } from '../modules/backgroundTask';
 import { BillingModule } from '../modules/billing/billing';
 import { BiometricsModule } from '../modules/biometrics';
 import { BrowserModule } from '../modules/browser';
@@ -101,6 +102,7 @@ export class NativeKit {
   public readonly oauth = new OAuthModule(this);
   public readonly billing = new BillingModule(this);
   public readonly updates = new UpdatesModule(this);
+  public readonly backgroundTask = new BackgroundTaskModule(this);
 
   public handshakeInfo: Handshake | null = null;
   public options: NativeKitOptions;
@@ -133,6 +135,9 @@ export class NativeKit {
         this.handshakeInfo = handshake;
         // Zero-config: a native server-loader app begins polling for remote updates.
         this.updates.__autostart();
+        // A background launch carries the wake id in the handshake → dispatch the registered handler
+        // (the app's boot register() may have already run, or land moments later — both dispatch).
+        this.backgroundTask.__onReady(handshake.backgroundTaskId);
         return this.handshakeInfo;
       })();
     }

package/src/core/types.ts

@@ -24,6 +24,11 @@ export interface Handshake {
   platform: Platform;
   app: AppInfo;
   capabilities: Record<string, Capability>;
+  /** Set ONLY on a background launch: the OS woke the app (possibly cold, headless, no visible
+   * WebView) to run this registered background-task id. The shell populates it; `kit.backgroundTask`
+   * reads it from {@link NativeKit.handshakeInfo} and dispatches the registered handler. Absent on a
+   * normal foreground launch. See {@link BackgroundTaskModule}. */
+  backgroundTaskId?: string;
   /** Optional diagnostic payload (breadcrumbs, etc.). */
   debug?: Record<string, unknown>;
 }

package/src/core/web-adapter.ts

@@ -88,10 +88,15 @@ export class WebAdapter implements NativeKitAdapter {
         typeof (window as any).webkitSpeechRecognition !== 'undefined'
           ? 'web'
           : 'none',
-      app: 'web', // openUrl via window.open; openSettings unsupported
+      app: 'web', // openUrl via window.open; openSettings/canOpenUrl unsupported
+      shortcuts: 'none', // no home-screen quick actions for a PWA
+      privacyScreen: 'none', // a browser can't hide content in the app-switcher or block screenshots
       browser: 'web', // new tab/window
       billing: 'none', // no IAP in a plain browser — wire a web checkout yourself
       push: 'none', // remote push (APNs/FCM) is native-only — web push (VAPID) is the app's own concern
+      // headless background execution is native-only — a PWA's Background/Periodic Sync lives in a
+      // service worker the kit doesn't own → honest 'none' (schedule/cancel resolve as no-ops).
+      backgroundTask: 'none',
     };
     return {
       protocol: 1,
@@ -395,6 +400,14 @@ export class WebAdapter implements NativeKitAdapter {
       case 'app.openSettings':
         throw new KitError('UNSUPPORTED', 'No app settings page on web');
 
+      case 'app.canOpenUrl':
+        // A PWA can't probe installed apps — be honest rather than guess from the scheme.
+        return false as T;
+      case 'app.setShortcuts':
+        return undefined as T; // no home-screen quick actions in a browser — no-op (cap reported 'none')
+      case 'screen.setPrivacy':
+        return undefined as T; // a browser can't hide content in the app-switcher — no-op (cap 'none')
+
       case 'app.environment':
         // On web there's no install — report the honest 'web' source. is_emulator is native-only.
         return { source: 'web', isEmulator: false } as T;
@@ -417,9 +430,14 @@ export class WebAdapter implements NativeKitAdapter {
       case 'push.requestPermission':
       case 'push.register':
       case 'push.unregister':
-      case 'push.sendTest':
         throw new KitError('UNSUPPORTED', 'No native remote push on web — use Web Push (VAPID) in your app, or run inside the appwrap shell');
 
+      case 'backgroundTask.schedule':
+      case 'backgroundTask.cancel':
+        // Honest no-op: a browser has no OS-scheduled headless wake the kit owns (that's a service
+        // worker's Background/Periodic Sync). Resolve so callers don't have to branch on platform.
+        return undefined as T;
+
       default:
         throw new KitError('UNSUPPORTED', `Unknown method: ${method}`);
     }

package/src/index.ts

@@ -1,6 +1,6 @@
 export { NativeKit, NativeKitOptions, kit } from './core/NativeKit';
 export type { KitContext } from './core/NativeKit';
-export type { AppEnvironment, InstallSource } from './modules/app';
+export type { AppEnvironment, AppShortcut, InstallSource } from './modules/app';
 export { AppwrapAdapter } from './core/appwrap-adapter';
 export { WebAdapter } from './core/web-adapter';
 export { KitError } from './core/types';
@@ -45,6 +45,8 @@ export { ClientTrustedValidator, HttpValidator, HttpValidatorOptions } from './m
 export { HttpBillingProvider, HttpBillingProviderOptions } from './modules/billing/providers';
 export type { HeaderProvider } from './modules/billing/http';
 export { HealthModule } from './modules/health';
+export { BackgroundTaskModule } from './modules/backgroundTask';
+export type { BackgroundTaskHandler, ScheduleBackgroundTaskOptions } from './modules/backgroundTask';
 export type {
   BillingProvider,
   BillingValidator,

package/src/modules/app.ts

@@ -1,4 +1,13 @@
 import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+/** A home-screen long-press quick action. `id` is echoed back to {@link AppModule.onShortcut} when
+ *  the user activates it; keep it stable so your router can map it. Custom icons are v1-omitted. */
+export interface AppShortcut {
+  id: string;
+  title: string;
+  subtitle?: string;
+}
 
 /** Where this build was installed from. Drives beta-vs-prod analytics cohorts.
  *  - `appstore` / `playstore` — public store install
@@ -57,8 +66,49 @@ export class AppModule {
     return this.kit.invoke('app.openUrl', { url });
   }
 
+  /**
+   * Probe whether the OS can open `url` — i.e. some installed app (or the OS) handles its scheme.
+   * Use it to hide a "Open in <App>" button when the target app isn't installed.
+   *
+   * Common schemes (http/https/tel/mailto/sms) resolve without any declaration. To probe a CUSTOM
+   * scheme (e.g. `whatsapp://`) it MUST be declared up-front, else the OS reports false for privacy:
+   *  - Custom scheme, BOTH platforms — list the scheme in `appwrap.json.queryUrlSchemes`. It stamps iOS
+   *    Info.plist `LSApplicationQueriesSchemes` AND Android `<queries>` (a VIEW `<intent>` per scheme),
+   *    so a scheme probe works identically on iOS and Android with one declaration.
+   *  - Android explicit package (optional) — to probe a specific package directly, list it in
+   *    `appwrap.json.queryPackages` (→ AndroidManifest `<queries><package>`). Android-only.
+   * Web is always `false` — a PWA can't probe installed apps (honest).
+   */
+  canOpenUrl(url: string): Promise<boolean> {
+    return this.kit.invoke('app.canOpenUrl', { url });
+  }
+
   /** Open this app's page in the OS Settings app (to toggle permissions, etc.). */
   openSettings(): Promise<void> {
     return this.kit.invoke('app.openSettings');
   }
+
+  /** 'native' where the OS exposes home-screen quick actions (iOS 3D-Touch/long-press shortcut items;
+   *  Android 7.1+ app shortcuts) · else 'none'. Branch on this, not try/catch. */
+  get shortcutsCapability() {
+    return this.kit.capability('shortcuts');
+  }
+
+  /**
+   * Set the app's home-screen long-press quick actions (replaces any previously set). Pass `[]` to
+   * clear. iOS assigns `UIApplication.shortcutItems`; Android sets dynamic shortcuts (API 25+, no-op
+   * below); web is a no-op. Activation is delivered via {@link onShortcut}. Custom icons are v1-omitted.
+   */
+  setShortcuts(items: AppShortcut[]): Promise<void> {
+    return this.kit.invoke('app.setShortcuts', { items });
+  }
+
+  /**
+   * Fire when the user activates a home-screen shortcut, with its `id`. Like deep links, a shortcut
+   * that COLD-LAUNCHED the app is buffered natively until the handshake, so a listener registered at
+   * startup still receives it.
+   */
+  onShortcut(cb: (id: string) => void): Unsubscribe {
+    return this.kit.on('app.shortcut', (p) => cb((p as { id: string }).id));
+  }
 }

package/src/modules/backgroundTask.ts

@@ -0,0 +1,122 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/**
+ * A headless background-task handler. Runs (possibly cold, with no visible WebView) when the OS wakes
+ * the app for `ctx.id`. `ctx.signal` aborts when the OS budget is nearly spent (~25s, below the iOS
+ * ~30s ceiling) or the OS calls the expiration handler — observe it for any long await and bail
+ * promptly, or the OS may kill the app and refuse future wakes. Resolve when done; a rejection is
+ * reported to the OS as a failed run (it still reschedules).
+ */
+export type BackgroundTaskHandler = (ctx: { id: string; signal: AbortSignal }) => Promise<void>;
+
+/** Constraints for {@link BackgroundTaskModule.schedule}. The OS treats these as HINTS — actual wake
+ * timing is the OS's call (it batches by power/network/usage), so a wake is opportunistic, not a timer. */
+export interface ScheduleBackgroundTaskOptions {
+  /** Task id — must be one of `appwrap.json.backgroundTasks` (iOS requires identifiers declared at
+   * build time). The same id is matched against the wake handshake + the registered handler. */
+  id: string;
+  /** Earliest the OS should consider waking again (a floor, not a guarantee). iOS clamps app-refresh
+   * to its own minimum; Android `WorkManager` periodic work has a 15-min platform minimum. */
+  minIntervalMs?: number;
+  /** Only run when the network is reachable (iOS `BGProcessingTaskRequest.requiresNetworkConnectivity`
+   * / Android `NetworkType.CONNECTED`). */
+  requiresNetwork?: boolean;
+  /** Only run while charging (iOS `BGProcessingTaskRequest.requiresExternalPower` / Android
+   * `setRequiresCharging`). */
+  requiresCharging?: boolean;
+}
+
+/** Wall-clock guard below the iOS ~30s background budget. The kit aborts the signal at this point so a
+ * handler that ignores the OS expiration still releases the task before the OS force-kills the app. */
+const SAFETY_TIMEOUT_MS = 25_000;
+
+/**
+ * Headless background execution with a JS-handler contract — ONE API across platforms.
+ *
+ * Flow: at EVERY launch the app calls {@link register} (idempotent) for each task id. When the OS woke
+ * the app for a task, the handshake carries that id ({@link import('../core/types').Handshake.backgroundTaskId});
+ * the kit invokes the matching handler with an {@link AbortSignal}, arms a {@link SAFETY_TIMEOUT_MS}
+ * abort, and on resolve/reject/timeout calls `backgroundTask.finish` so the shell completes the OS
+ * task + reschedules (BGTask is one-shot — it MUST resubmit). Registration may land before OR after
+ * {@link NativeKit.ready} resolves; both orderings dispatch (a pending wake is replayed to a late
+ * registration, and an early registration is dispatched the moment ready resolves with a wake id).
+ *
+ * Native (iOS `BGTaskScheduler` + an offscreen `WKWebView`, Android `WorkManager` + a headless
+ * `WebView`) reports `capability === 'native'`. Web is honestly `'none'`: a PWA's background-sync
+ * lives in a service worker the kit doesn't own — {@link schedule}/{@link cancel} resolve as no-ops
+ * and {@link register} records nothing.
+ */
+export class BackgroundTaskModule {
+  private handlers = new Map<string, BackgroundTaskHandler>();
+  /** A wake id seen before its handler was registered — replayed on the late {@link register}. */
+  private pendingWakeId: string | null = null;
+  /** Ids already dispatched this session — guards against a double-fire (replay + ready both matching). */
+  private dispatched = new Set<string>();
+
+  constructor(private kit: NativeKit) {}
+
+  /** Called by {@link NativeKit.ready} once the handshake resolves (never triggers the handshake
+   * itself — same lazy contract as the rest of the kit). A background launch carries the wake id in
+   * the handshake: if its handler already registered (early) → dispatch now; else remember it for the
+   * late {@link register}. @internal */
+  __onReady(backgroundTaskId?: string): void {
+    if (!backgroundTaskId) return;
+    if (this.handlers.has(backgroundTaskId)) this.dispatch(backgroundTaskId);
+    else this.pendingWakeId = backgroundTaskId;
+  }
+
+  /** 'native' on a shell · 'none' on web (PWA background-sync is the app's service-worker concern). */
+  get capability() {
+    return this.kit.capability('backgroundTask');
+  }
+
+  /**
+   * Record the handler for `id`. Call at boot on EVERY launch (idempotent — re-registering replaces).
+   * If the app was woken for this id (the handshake carried it), the handler dispatches immediately,
+   * whether the wake was already known (ready resolved first) or arrives later.
+   */
+  register(id: string, handler: BackgroundTaskHandler): void {
+    this.handlers.set(id, handler);
+    if (this.pendingWakeId === id) {
+      this.pendingWakeId = null;
+      this.dispatch(id);
+    }
+  }
+
+  /** Ask the OS to (re)schedule a wake for `id`. No-op resolve on web. */
+  schedule(opts: ScheduleBackgroundTaskOptions): Promise<void> {
+    return this.kit.invoke<void>('backgroundTask.schedule', opts);
+  }
+
+  /** Cancel a scheduled task. No-op resolve on web. */
+  cancel(id: string): Promise<void> {
+    return this.kit.invoke<void>('backgroundTask.cancel', { id });
+  }
+
+  /** Run the registered handler under an abort-guarded budget, then report completion to the shell so
+   * it finishes the OS task + reschedules. Idempotent per id per session. */
+  private async dispatch(id: string): Promise<void> {
+    if (this.dispatched.has(id)) return;
+    this.dispatched.add(id);
+    const handler = this.handlers.get(id);
+    if (!handler) return;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SAFETY_TIMEOUT_MS);
+    let success = true;
+    try {
+      await handler({ id, signal: controller.signal });
+    } catch (e) {
+      success = false;
+      console.warn('[native-kit] backgroundTask handler rejected', id, e);
+    } finally {
+      clearTimeout(timer);
+      // Tell the shell to complete the OS task + resubmit the next request. The handler's own work is
+      // done; a finish-report failure must not mask it, so swallow (logged) — the OS budget is spent
+      // either way.
+      await this.kit
+        .invoke<void>('backgroundTask.finish', { id, success })
+        .catch((e) => console.warn('[native-kit] backgroundTask.finish failed', id, e));
+    }
+  }
+}

package/src/modules/push.ts

@@ -65,13 +65,6 @@ export class PushModule {
     return this.kit.invoke('push.unregister');
   }
 
-  /** Dev/demo: ask your backend (via `push.registrationUrl`) to push THIS device on demand. The shell
-   *  POSTs the token natively (no WebView CORS) with `test:true`. Resolves `{ status }` (the backend's
-   *  HTTP code). Requires a configured registrationUrl + a registered token. */
-  sendTest(): Promise<{ status: number }> {
-    return this.kit.invoke('push.sendTest', undefined, { timeoutMs: 20_000 });
-  }
-
   /** Foreground message delivery (app open, no tap). */
   onMessage(cb: (m: PushMessage) => void): Unsubscribe {
     return this.kit.on('push.message', (p) => cb(p as PushMessage));

package/src/modules/screen.ts

@@ -11,13 +11,29 @@ export type OrientationLock =
   | 'landscape-right'
   | 'any';
 
-/** Screen-level controls. Today: orientation; brightness/keepAwake live on `kit.ui`. */
+/** Screen-level controls. Today: orientation + privacy screen; brightness/keepAwake live on `kit.ui`. */
 export class ScreenModule {
   readonly orientation: OrientationController;
 
-  constructor(kit: NativeKit) {
+  constructor(private kit: NativeKit) {
     this.orientation = new OrientationController(kit);
   }
+
+  /** 'native' on a shell · else 'none' — the browser can't hide content in the app-switcher or block
+   *  screenshots. Branch on this, not try/catch. */
+  get privacyCapability() {
+    return this.kit.capability('privacyScreen');
+  }
+
+  /**
+   * Privacy screen — hide app content in the app-switcher / on backgrounding and block screenshots.
+   * `true` enables, `false` disables (the state persists across background/foreground until changed).
+   * iOS covers the window with a blur while inactive/backgrounded; Android sets `FLAG_SECURE` (which
+   * also blocks screenshots and screen recording — expected). Web is an honest no-op.
+   */
+  setPrivacy(enabled: boolean): Promise<void> {
+    return this.kit.invoke('screen.setPrivacy', { enabled });
+  }
 }
 
 /**