@livx.cc/native-kit 0.16.1 → 0.18.0

package/README.md

@@ -13,6 +13,17 @@ await kit.haptics.impact('medium');     // native vibration in the shell, no-op/
 const photo = await kit.photos.pick();  // native picker on device, <input type=file> on web
 ```
 
+### Analytics context
+
+`kit.context()` returns one flat, vendor-neutral property bag (client taxonomy, app version/build, install source, device, push permission, …) — spread it straight into your analytics super-properties. Native-only fields degrade gracefully on web. First-party & non-tracking: the install id is iOS IDFV / an Android UUID, never IDFA/GAID.
+
+```ts
+import { kit } from '@livx.cc/native-kit';
+mixpanel.register(await kit.context());
+// → { client: 'native-ios', platform: 'ios', app_version: '1.0.3',
+//     install_source: 'testflight', device_model: 'iPhone15,3', push_permission: 'granted', … }
+```
+
 The kit detects whether it's running inside the appwrap shell and routes each call to the native bridge or a web fallback, so a single web build works everywhere. Capabilities advertise their real backing (`native` / `web` / `none`) so your UI can be honest about what's available.
 
 Covers haptics, share, storage, notifications, OAuth, billing (IAP), health, geo, camera, photos, contacts, calendar, motion, reviews, and more.

package/package.json

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

package/src/core/NativeKit.ts

@@ -26,6 +26,7 @@ import { ShareModule } from '../modules/share';
 import { StorageModule } from '../modules/storage';
 import { ToastModule } from '../modules/toast';
 import { UiModule } from '../modules/ui';
+import { UpdatesModule } from '../modules/updates';
 
 export class NativeKitOptions {
   /** Priority order; first adapter whose detect() passes wins. */
@@ -33,6 +34,38 @@ export class NativeKitOptions {
   handshakeTimeoutMs = 3000;
 }
 
+/**
+ * Flat, vendor-neutral analytics bag — spread straight into your analytics provider's
+ * super-properties (e.g. `mixpanel.register(await kit.context())`). Native-only fields
+ * degrade gracefully (omitted/undefined) on web and on older shells. snake_case keys
+ * match common analytics conventions.
+ */
+export interface KitContext {
+  /** Coarse runtime taxonomy: 'native-ios' | 'native-android' | 'web'. */
+  client: string;
+  is_native: boolean;
+  platform: Platform;
+  app_id?: string;
+  app_name?: string;
+  app_version?: string;
+  app_build?: string;
+  /** App Store / TestFlight / sideload / simulator / web. */
+  install_source?: string;
+  /** Stable per-install id (iOS IDFV / Android UUID) — first-party, non-tracking. */
+  install_id?: string;
+  first_install_at?: number;
+  last_update_at?: number;
+  is_emulator?: boolean;
+  device_model?: string;
+  device_os?: string;
+  device_os_version?: string;
+  device_manufacturer?: string;
+  device_language?: string;
+  device_region?: string;
+  push_permission?: string;
+  network_type?: string;
+}
+
 export class NativeKit {
   public readonly haptics = new HapticsModule(this);
   public readonly share = new ShareModule(this);
@@ -59,11 +92,13 @@ export class NativeKit {
   public readonly browser = new BrowserModule(this);
   public readonly oauth = new OAuthModule(this);
   public readonly billing = new BillingModule(this);
+  public readonly updates = new UpdatesModule(this);
 
   public handshakeInfo: Handshake | null = null;
   public options: NativeKitOptions;
   private adapter: NativeKitAdapter | null = null;
   private readyPromise: Promise<Handshake> | null = null;
+  private contextPromise: Promise<KitContext> | null = null;
 
   constructor(options?: Partial<NativeKitOptions>) {
     this.options = { ...new NativeKitOptions(), ...options };
@@ -88,12 +123,65 @@ export class NativeKit {
           );
         }
         this.handshakeInfo = handshake;
+        // Zero-config: a native server-loader app begins polling for remote updates.
+        this.updates.__autostart();
         return this.handshakeInfo;
       })();
     }
     return this.readyPromise;
   }
 
+  /**
+   * One flat analytics bag (handshake + device + install env + push perm + network),
+   * ready to spread into super-properties. Resilient: each native probe degrades to
+   * omitted on failure, so this never rejects once {@link ready} resolves. Cached.
+   */
+  context(): Promise<KitContext> {
+    if (!this.contextPromise) {
+      this.contextPromise = (async () => {
+        await this.ready();
+        const hs = this.handshakeInfo!;
+        const client = this.is.native ? `native-${hs.platform}` : 'web';
+        const ctx: KitContext = {
+          client,
+          is_native: this.is.native,
+          platform: hs.platform,
+          app_id: hs.app?.id,
+          app_name: hs.app?.name,
+          app_version: hs.app?.version,
+          app_build: hs.app?.build,
+        };
+        // Probe in parallel; a failing/absent capability simply leaves its fields unset.
+        const safe = <T>(p: Promise<T>): Promise<T | null> => p.catch(() => null);
+        const [env, device, push, net] = await Promise.all([
+          safe(this.app.environment()),
+          safe(this.device.info()),
+          this.push.capability === 'native' ? safe(this.push.permissionStatus()) : Promise.resolve(null),
+          safe(this.network.status()),
+        ]);
+        if (env) {
+          ctx.install_source = env.source;
+          ctx.install_id = env.installId;
+          ctx.first_install_at = env.firstInstallAt;
+          ctx.last_update_at = env.lastUpdateAt;
+          ctx.is_emulator = env.isEmulator;
+        }
+        if (device) {
+          ctx.device_model = device.model;
+          ctx.device_os = device.os;
+          ctx.device_os_version = device.osVersion;
+          ctx.device_manufacturer = device.manufacturer;
+          ctx.device_language = device.language;
+          ctx.device_region = device.region;
+        }
+        if (push) ctx.push_permission = push;
+        if (net) ctx.network_type = net.type;
+        return ctx;
+      })();
+    }
+    return this.contextPromise;
+  }
+
   get is() {
     return { native: this.adapter?.kind === 'appwrap', web: this.adapter?.kind === 'web' };
   }

package/src/core/types.ts

@@ -14,6 +14,9 @@ export interface AppInfo {
   name: string;
   version: string;
   build?: string;
+  /** How the shell loads content: 'app'/'file' (bundled) or 'server' (remote URL). Drives
+   * remote-update detection (only meaningful for 'server'). Absent on web/older shells. */
+  loader?: 'app' | 'file' | 'server';
 }
 
 export interface Handshake {

package/src/core/web-adapter.ts

@@ -322,6 +322,17 @@ export class WebAdapter implements NativeKitAdapter {
       case 'app.openSettings':
         throw new KitError('UNSUPPORTED', 'No app settings page on web');
 
+      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;
+
+      case 'push.permissionStatus': {
+        // Best-effort via the Notification API (web push ≠ native push, but the perm signal is useful).
+        if (!('Notification' in window)) return 'notDetermined' as T;
+        const perm = Notification.permission; // 'granted' | 'denied' | 'default'
+        return (perm === 'default' ? 'notDetermined' : perm) as T;
+      }
+
       case 'billing.products':
       case 'billing.purchase':
       case 'billing.restore':

package/src/index.ts

@@ -1,4 +1,6 @@
 export { NativeKit, NativeKitOptions, kit } from './core/NativeKit';
+export type { KitContext } from './core/NativeKit';
+export type { AppEnvironment, InstallSource } from './modules/app';
 export { AppwrapAdapter } from './core/appwrap-adapter';
 export { WebAdapter } from './core/web-adapter';
 export { KitError } from './core/types';
@@ -29,6 +31,7 @@ export type { AudioMode, MediaDeviceLite } from './modules/media';
 export type { NetworkStatus } from './modules/network';
 export type { ActionOptions, AlertOptions, ConfirmOptions, SafeAreaInsets } from './modules/ui';
 export type { MotionSample } from './modules/motion';
+export type { UpdateStatus, UpdatesOptions } from './modules/updates';
 export type { PickedContact } from './modules/contacts';
 export type { CalendarEventOptions } from './modules/calendar';
 export type { BrowserOptions } from './modules/browser';

package/src/modules/app.ts

@@ -1,5 +1,28 @@
 import type { NativeKit } from '../core/NativeKit';
 
+/** Where this build was installed from. Drives beta-vs-prod analytics cohorts.
+ *  - `appstore` / `playstore` — public store install
+ *  - `testflight` — iOS beta
+ *  - `sideload` — direct install (dev build, ad-hoc, APK), or unknown installer
+ *  - `simulator` — running on a simulator/emulator
+ *  - `web` — not running inside the native shell */
+export type InstallSource = 'appstore' | 'playstore' | 'testflight' | 'sideload' | 'simulator' | 'web';
+
+/** Install-level environment facts the page can't derive itself. First-party,
+ *  non-tracking (no IDFA/GAID): `installId` is iOS IDFV / an Android UUID kept in
+ *  app storage — app-scoped and reset on uninstall. */
+export interface AppEnvironment {
+  source: InstallSource;
+  /** Stable per-install id (iOS identifierForVendor / Android random UUID). */
+  installId?: string;
+  /** First install epoch-ms (Android only; omitted on iOS — no clean API). */
+  firstInstallAt?: number;
+  /** Last update epoch-ms (Android only). */
+  lastUpdateAt?: number;
+  /** Running on a simulator/emulator. */
+  isEmulator: boolean;
+}
+
 /** System-level app actions: hand a URL to the OS, or open this app's settings page. */
 export class AppModule {
   constructor(private kit: NativeKit) {}
@@ -8,6 +31,11 @@ export class AppModule {
     return this.kit.capability('app');
   }
 
+  /** Install-level environment facts for analytics/identification (source, install id, timestamps). */
+  environment(): Promise<AppEnvironment> {
+    return this.kit.invoke('app.environment');
+  }
+
   /** Open a URL in the OS default handler (external browser, mail:, tel:, maps:, …). */
   openUrl(url: string): Promise<void> {
     return this.kit.invoke('app.openUrl', { url });

package/src/modules/push.ts

@@ -49,6 +49,12 @@ export class PushModule {
     return this.kit.invoke('push.requestPermission', undefined, { timeoutMs: 60_000 });
   }
 
+  /** Current authorization WITHOUT prompting — for opt-in funnel analytics.
+   * 'notDetermined' means the user hasn't been asked yet. */
+  permissionStatus(): Promise<'granted' | 'denied' | 'notDetermined'> {
+    return this.kit.invoke('push.permissionStatus');
+  }
+
   /** Register with APNs/FCM and resolve the device token. Call after permission is granted. */
   register(): Promise<PushToken> {
     return this.kit.invoke('push.register', undefined, { timeoutMs: 30_000 });

package/src/modules/updates.ts

@@ -0,0 +1,164 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+export interface UpdateStatus {
+  /** Version the running bundle BOOTED with (embedded), or '' if it couldn't be determined. */
+  current: string;
+  /** Version advertised by the live manifest, or '' if the fetch failed. */
+  latest: string;
+  /** Optional build identifier from the manifest. */
+  build?: string | number;
+  /** True only when both versions are known AND differ — never on an unknown `current`. */
+  updateAvailable: boolean;
+}
+
+export interface UpdatesOptions {
+  /** Version-manifest URL — a tiny JSON `{ version: string, build?: string|number }`.
+   * Default: `${location.origin}/version.json`. */
+  manifestUrl?: string;
+  /** Poll cadence (ms). Always also checks on app resume. 0 = resume-only. Default 60_000. */
+  pollIntervalMs?: number;
+  /** Version the running bundle booted with. Default: `window.__APP_VERSION__` →
+   * `<meta name="app-version">`. Supplying the bundle's OWN embedded version is what
+   * makes the prompt trustworthy (see class doc). */
+  currentVersion?: string;
+  /** Auto-show a persistent native "tap to reload" banner when an update is detected. Default true. */
+  autoPrompt?: boolean;
+}
+
+/**
+ * Remote-update detection for `loader:'server'` apps.
+ *
+ * Polls a version manifest and compares it to the version the running bundle **booted with**
+ * (its embedded `__APP_VERSION__`), NOT to a previous manifest read. That distinction is the
+ * whole point: comparing manifest-to-manifest gives a phantom "update available" the moment a
+ * deploy bumps the manifest but ships the old bundle (a real bug we've hit). Embedded-vs-manifest
+ * only fires when the bytes actually running are behind the deploy.
+ *
+ * Auto-starts for server-loader native apps (zero app code); apps can also drive it manually via
+ * {@link check}/{@link onAvailable}/{@link reload} or re-{@link start} with their own options.
+ */
+export class UpdatesModule {
+  private started = false;
+  private opts: Required<UpdatesOptions> | null = null;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private unsubs: Unsubscribe[] = [];
+  private listeners = new Set<(s: UpdateStatus) => void>();
+  private prompted = false;
+
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('updates');
+  }
+
+  /** Fetch the manifest and compare to the boot version. Reports the result up to the shell
+   * (for the dev-menu App Info screen) and fires {@link onAvailable} listeners on a fresh update. */
+  async check(): Promise<UpdateStatus> {
+    const o = this.opts ?? this.resolveOptions();
+    const current = o.currentVersion;
+    let latest = '';
+    let build: string | number | undefined;
+    try {
+      // `no-store` skips the HTTP cache — but a cache-first service worker would still intercept and
+      // serve a stale manifest, so the SW recipe must let `version.json` pass through to the network.
+      const res = await fetch(o.manifestUrl, { cache: 'no-store' });
+      if (res.ok) {
+        const j = (await res.json()) as { version?: string; build?: string | number };
+        latest = String(j?.version ?? '');
+        build = j?.build;
+      }
+    } catch (e) {
+      // Offline or no manifest deployed — not fatal; log and report "unknown latest".
+      console.warn('[updates] manifest fetch failed:', (e as Error)?.message ?? e);
+    }
+    const updateAvailable = !!current && !!latest && current !== latest;
+    const status: UpdateStatus = { current, latest, build, updateAvailable };
+
+    // Surface to native so the shake → App Info screen can show "got the latest?".
+    this.kit.invoke('app.reportWebVersion', status).catch((e) =>
+      console.warn('[updates] reportWebVersion failed:', (e as Error)?.message ?? e)
+    );
+
+    if (updateAvailable) {
+      this.listeners.forEach((cb) => cb(status));
+      if (o.autoPrompt && !this.prompted) {
+        this.prompted = true;
+        this.kit
+          .invoke('toast.banner', { id: 'appwrap.update', message: 'New version available — tap to reload' })
+          .catch((e) => console.warn('[updates] banner failed:', (e as Error)?.message ?? e));
+      }
+    }
+    return status;
+  }
+
+  /** Notify whenever a manifest check finds the running bundle is behind. */
+  onAvailable(cb: (s: UpdateStatus) => void): Unsubscribe {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+
+  /** Hard reload the WebView, bypassing cache (iOS `reloadFromOrigin`, Android cache-clear + reload). */
+  reload(): Promise<void> {
+    return this.kit.invoke('app.reload');
+  }
+
+  /** Begin polling + resume/banner wiring. Idempotent; re-calling replaces options. */
+  start(options?: UpdatesOptions): void {
+    this.opts = this.resolveOptions(options);
+    if (this.started) {
+      this.stop(/* keepStarted */ true);
+    }
+    this.started = true;
+    // A reload picks up the new bundle → allow a fresh prompt next time.
+    this.unsubs.push(this.kit.on('app.resume', () => void this.check()));
+    // Banner tap (or any 'appwrap.update' action) → reload.
+    this.unsubs.push(
+      this.kit.on('toast.action', (p) => {
+        if ((p as { id?: string })?.id === 'appwrap.update') void this.reload();
+      })
+    );
+    if (this.opts.pollIntervalMs > 0) {
+      this.timer = setInterval(() => void this.check(), this.opts.pollIntervalMs);
+    }
+    void this.check();
+  }
+
+  stop(keepStarted = false): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.unsubs.forEach((u) => u());
+    this.unsubs = [];
+    if (!keepStarted) this.started = false;
+  }
+
+  /** Called by NativeKit.ready() — self-starts only for a native server-loader app. */
+  __autostart(): void {
+    if (this.started) return;
+    if (this.kit.is.native && this.kit.handshakeInfo?.app?.loader === 'server') this.start();
+  }
+
+  private resolveOptions(o?: UpdatesOptions): Required<UpdatesOptions> {
+    const origin = typeof location !== 'undefined' ? location.origin : '';
+    return {
+      manifestUrl: o?.manifestUrl ?? `${origin}/version.json`,
+      pollIntervalMs: o?.pollIntervalMs ?? 60_000,
+      currentVersion: o?.currentVersion ?? bootVersion(),
+      autoPrompt: o?.autoPrompt ?? true,
+    };
+  }
+}
+
+/** Embedded version the running bundle shipped with: `window.__APP_VERSION__`, then a
+ * `<meta name="app-version">` tag. '' (unknown) when neither is present — in which case we never
+ * raise a false update prompt. */
+function bootVersion(): string {
+  const g = typeof window !== 'undefined' ? (window as any).__APP_VERSION__ : undefined;
+  if (g) return String(g);
+  if (typeof document !== 'undefined') {
+    const meta = document.querySelector('meta[name="app-version"]');
+    const c = meta?.getAttribute('content');
+    if (c) return c;
+  }
+  return '';
+}