@livx.cc/native-kit 0.16.0 → 0.17.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elya Livshitz
+
+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

@@ -0,0 +1,35 @@
+# @livx.cc/native-kit
+
+Isomorphic native-capabilities kit for PWAs — the **same API in the browser and inside an [appwrap](https://github.com/Livshitz/appwrap) native shell**. Zero dependencies.
+
+```bash
+bun add @livx.cc/native-kit   # or: npm i @livx.cc/native-kit
+```
+
+```ts
+import { kit } from '@livx.cc/native-kit';
+
+await kit.haptics.impact('medium');     // native vibration in the shell, no-op/web-fallback in a browser
+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.
+
+**Full documentation, capability model, and the bridge protocol:** see the [appwrap README](https://github.com/Livshitz/appwrap#readme).
+
+## License
+
+MIT © Elya Livshitz

package/package.json

@@ -1,7 +1,28 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.16.0",
+  "version": "0.17.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",
+  "homepage": "https://github.com/Livshitz/appwrap#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Livshitz/appwrap.git",
+    "directory": "packages/native-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/Livshitz/appwrap/issues"
+  },
+  "keywords": [
+    "pwa",
+    "native",
+    "webview",
+    "nativescript",
+    "appwrap",
+    "isomorphic",
+    "ios",
+    "android"
+  ],
   "type": "module",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
@@ -16,7 +37,7 @@
     "src"
   ],
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --format esm && bun build src/index.ts --outfile dist/native-kit.iife.js --format iife --global-name NativeKitLib"
+    "build": "bun build src/index.ts --outdir=dist --format=esm && bun build src/index.ts --outfile=dist/native-kit.iife.js --format=iife --global-name=NativeKitLib"
   },
   "devDependencies": {
     "typescript": "^5.4.0"

package/src/core/NativeKit.ts

@@ -33,6 +33,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);
@@ -64,6 +96,7 @@ export class NativeKit {
   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 };
@@ -94,6 +127,57 @@ export class NativeKit {
     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/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';

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/billing/types.ts

@@ -1,5 +1,5 @@
 /** Billing / IAP contract — platform-neutral shapes shared by the module,
- *  the native handlers, and any pluggable validator (Bodify / RevenueCat / IAPHUB / custom). */
+ *  the native handlers, and any pluggable validator (RevenueCat / IAPHUB / custom). */
 
 export type ProductType =
   | 'consumable'
@@ -61,7 +61,7 @@ export interface PurchaseResult {
 /**
  * The swappable seam. The kit owns the on-device purchase flow; *who decides the
  * user is actually entitled* is up to the app. Implement this (or configure the
- * bundled `HttpValidator`) to point at Bodify, RevenueCat, IAPHUB, or your own backend.
+ * bundled `HttpValidator`) to point at RevenueCat, IAPHUB, or your own backend.
  */
 export interface BillingValidator {
   /** Validate a fresh purchase/restore receipt → the entitlements it grants. */

package/src/modules/billing/validators.ts

@@ -38,7 +38,7 @@ export class HttpValidatorOptions {
 }
 
 /**
- * Generic server-validated strategy. One implementation covers Bodify, RevenueCat,
+ * Generic server-validated strategy. One implementation covers RevenueCat,
  * IAPHUB, or any custom backend — they differ only by URL, auth header, and a small
  * response mapper. HTTP over SDK by design (no vendor packages).
  */

package/src/modules/push.ts

@@ -5,7 +5,7 @@ import { KitError, type Capability, type Unsubscribe } from '../core/types';
 export type PushPlatform = 'apns' | 'fcm';
 
 /** A device push token + its transport. The kit's job ENDS here: ship this to YOUR backend
- * (Bodify / FCM-direct / OneSignal / custom) — the framework never sends, so it's push-platform-agnostic. */
+ * (FCM-direct / OneSignal / custom) — the framework never sends, so it's push-platform-agnostic. */
 export interface PushToken {
   platform: PushPlatform;
   token: string;
@@ -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 });