@livx.cc/native-kit 0.32.3 → 0.34.0

package/README.md

@@ -26,7 +26,7 @@ mixpanel.register(await kit.context());
 
 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.
+Covers haptics, share, storage, notifications, OAuth, billing (IAP), health, geo, camera, photos, contacts, calendar, motion, reviews, tracking (iOS App Tracking Transparency), and more.
 
 **Full documentation, capability model, and the bridge protocol:** see the [appwrap README](https://github.com/Livshitz/appwrap#readme).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.32.3",
+  "version": "0.34.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

@@ -30,6 +30,7 @@ import { ShareModule } from '../modules/share';
 import { SpeechModule } from '../modules/speech';
 import { StorageModule } from '../modules/storage';
 import { ToastModule } from '../modules/toast';
+import { TrackingModule } from '../modules/tracking';
 import { UiModule } from '../modules/ui';
 import { UpdatesModule } from '../modules/updates';
 
@@ -103,6 +104,7 @@ export class NativeKit {
   public readonly billing = new BillingModule(this);
   public readonly updates = new UpdatesModule(this);
   public readonly backgroundTask = new BackgroundTaskModule(this);
+  public readonly tracking = new TrackingModule(this);
 
   public handshakeInfo: Handshake | null = null;
   public options: NativeKitOptions;

package/src/core/types.ts

@@ -29,6 +29,12 @@ export interface Handshake {
    * reads it from {@link NativeKit.handshakeInfo} and dispatches the registered handler. Absent on a
    * normal foreground launch. See {@link BackgroundTaskModule}. */
   backgroundTaskId?: string;
+  /** Set ONLY on a cold launch FROM a deep link (url-scheme open or notification tap that started the
+   * app): the link that launched us, handed back synchronously so the PWA can route to the target
+   * route BEFORE first paint — avoiding a brief home-screen flash. A WARM deep link (app already
+   * running) is NOT carried here; it arrives via the `deeplink.open` event. Read it at `ready()` via
+   * {@link LifecycleModule.launchDeepLink}. Absent on a normal launch. */
+  deepLink?: string;
   /** Optional diagnostic payload (breadcrumbs, etc.). */
   debug?: Record<string, unknown>;
 }

package/src/index.ts

@@ -41,6 +41,7 @@ export type { SpeechVoice, SpeakOptions, ListenOptions, SpeechPartial } from './
 export type { CalendarEventOptions } from './modules/calendar';
 export type { BrowserOptions } from './modules/browser';
 export type { OAuthAuthorizeParams, OAuthResult } from './modules/oauth';
+export type { TrackingStatus } from './modules/tracking';
 export { ClientTrustedValidator, HttpValidator, HttpValidatorOptions } from './modules/billing/validators';
 export { HttpBillingProvider, HttpBillingProviderOptions } from './modules/billing/providers';
 export type { HeaderProvider } from './modules/billing/http';

package/src/modules/lifecycle.ts

@@ -20,4 +20,15 @@ export class LifecycleModule {
   onDeepLink(cb: (url: string) => void): Unsubscribe {
     return this.kit.on('deeplink.open', (p) => cb((p as { url: string }).url));
   }
+
+  /**
+   * The deep link the app was COLD-LAUNCHED from (url-scheme open / notification tap that started the
+   * app), if any — exposed synchronously from the handshake so the app can route to the target route
+   * BEFORE first paint and skip the brief home flash. Returns null on a normal launch or on web.
+   * Available once `kit.ready()` has resolved. Warm deep links (app already open) do NOT appear here —
+   * subscribe to {@link onDeepLink} for those.
+   */
+  get launchDeepLink(): string | null {
+    return this.kit.handshakeInfo?.deepLink ?? null;
+  }
 }

package/src/modules/tracking.ts

@@ -0,0 +1,73 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/** App Tracking Transparency authorization status (iOS ATTrackingManager). Mirrors Apple's enum.
+ *  - `notDetermined` — the user hasn't been asked yet (call {@link TrackingModule.requestPermission}).
+ *  - `restricted`    — tracking is disallowed by device policy (e.g. parental controls / MDM).
+ *  - `denied`        — the user declined; you MUST NOT track / read the IDFA.
+ *  - `authorized`    — the user allowed tracking; {@link TrackingModule.idfa} returns the IDFA. */
+export type TrackingStatus = 'notDetermined' | 'restricted' | 'denied' | 'authorized';
+
+/**
+ * App Tracking Transparency (iOS, `tracking` module — opt-in). The native-only compliance seam for
+ * apps that track the user across other companies' apps/sites (IDFA, cross-app identity): Apple
+ * REQUIRES the ATT prompt + `NSUserTrackingUsageDescription` and forbids tracking before consent.
+ *
+ * Provider-agnostic, like `kit.push`/`kit.oauth`: the shell owns only the device-side primitive
+ * (show the prompt, report status, hand back the IDFA when authorized). What you DO with consent —
+ * init an ad SDK, set an analytics super-prop — is the PWA's job.
+ *
+ * Capability gating (honest):
+ *  - iOS (14.5+): `'native'`.
+ *  - Android / web / iOS < 14.5: `'none'` — there is NO ATT. The methods still resolve safely:
+ *    `requestPermission()`/`status()` → `'authorized'` (no consent gate exists, so tracking is not
+ *    blocked by the OS — Play's Advertising-ID consent is a separate, app-declared concern), and
+ *    `idfa()` → `undefined` (the IDFA is iOS-only; GAID needs the AD_ID permission + Play's own flow).
+ *
+ * Most apps need only first-party analytics and should NOT enable this module (no string = Apple
+ * assumes no tracking). Ship it only when the app genuinely tracks across companies.
+ */
+export class TrackingModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('tracking');
+  }
+
+  /** Honest fallback when ATT doesn't exist (Android/web/iOS<14.5): nothing gates tracking at the OS
+   *  level, so report `authorized` rather than a misleading `notDetermined`. */
+  private get fallback(): TrackingStatus {
+    return 'authorized';
+  }
+
+  /**
+   * Show the iOS ATT prompt and resolve with the resulting status. The prompt only appears once per
+   * install while status is `notDetermined`; subsequent calls resolve immediately with the prior
+   * choice. Dismiss-bound (the user decides at their leisure) → no watchdog timeout.
+   * On a non-ATT platform resolves to {@link fallback} without showing UI.
+   */
+  requestPermission(): Promise<TrackingStatus> {
+    if (this.capability !== 'native') return Promise.resolve(this.fallback);
+    return this.kit.invoke<TrackingStatus>('tracking.requestPermission', undefined, { timeoutMs: 'none' });
+  }
+
+  /** Current ATT authorization status WITHOUT prompting. {@link fallback} on a non-ATT platform. */
+  status(): Promise<TrackingStatus> {
+    if (this.capability !== 'native') return Promise.resolve(this.fallback);
+    return this.kit.invoke<TrackingStatus>('tracking.status');
+  }
+
+  /** Alias of {@link status} (parity with other permissioned modules' `permissionStatus`). */
+  permissionStatus(): Promise<TrackingStatus> {
+    return this.status();
+  }
+
+  /**
+   * The IDFA (iOS advertising identifier) — returned ONLY while ATT status is `authorized`; otherwise
+   * (denied/restricted/notDetermined, or the all-zero placeholder) resolves `undefined`. Always
+   * `undefined` off iOS (no IDFA exists — use Play's Advertising ID via your own flow if needed).
+   */
+  idfa(): Promise<string | undefined> {
+    if (this.capability !== 'native') return Promise.resolve(undefined);
+    return this.kit.invoke<string | undefined>('tracking.idfa');
+  }
+}