@livx.cc/native-kit 0.32.1 → 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.1",
+  "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/appwrap-adapter.ts

@@ -45,6 +45,12 @@ export class AppwrapAdapter implements NativeKitAdapter {
     return this.request<T>(method, params, opts?.timeoutMs ?? 10_000);
   }
 
+  /** `'none'` or `0` → no watchdog (dismiss-bound calls); otherwise the deadline in ms. */
+  private static resolveTimeout(timeoutMs: number | 'none'): number | null {
+    if (timeoutMs === 'none' || timeoutMs === 0) return null;
+    return timeoutMs;
+  }
+
   on(event: string, cb: (payload: unknown) => void): Unsubscribe {
     let set = this.listeners.get(event);
     if (!set) this.listeners.set(event, (set = new Set()));
@@ -52,14 +58,17 @@ export class AppwrapAdapter implements NativeKitAdapter {
     return () => set!.delete(cb);
   }
 
-  private request<T>(method: string, params: unknown, timeoutMs: number): Promise<T> {
+  private request<T>(method: string, params: unknown, timeoutMs: number | 'none'): Promise<T> {
     const id = `k${++this.seq}`;
     const envelope: RequestEnvelope = { v: 1, id, kind: 'request', method, params };
+    const deadline = AppwrapAdapter.resolveTimeout(timeoutMs);
     return new Promise<T>((resolve, reject) => {
-      const timer = setTimeout(() => {
+      // `null` deadline = dismiss-bound call: no watchdog, resolves only on the
+      // native response (e.g. the user closes the sheet).
+      const timer = deadline === null ? undefined : setTimeout(() => {
         this.pending.delete(id);
-        reject(new KitError('TIMEOUT', `${method} timed out after ${timeoutMs}ms`));
-      }, timeoutMs);
+        reject(new KitError('TIMEOUT', `${method} timed out after ${deadline}ms`));
+      }, deadline);
       this.pending.set(id, {
         resolve: (v) => { clearTimeout(timer); resolve(v as T); },
         reject: (e) => { clearTimeout(timer); reject(e); },

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>;
 }
@@ -71,9 +77,19 @@ export class KitError extends Error {
 export type Unsubscribe = () => void;
 
 export interface InvokeOptions {
-  /** Per-call response deadline. Interactive flows (pickers, dialogs, auth
-   * prompts) should pass a generous one — the user may take their time. */
-  timeoutMs?: number;
+  /** Per-call response deadline (default 10_000ms).
+   *
+   * Interactive flows (pickers, dialogs, auth prompts) should pass a generous
+   * value — the user may take their time.
+   *
+   * Pass `'none'` (or `0`) to DISABLE the watchdog entirely. Use this ONLY for
+   * dismiss-bound / present-and-wait calls: native UI that resolves solely when
+   * the user dismisses a sheet/modal (manage-subscriptions sheet,
+   * ASWebAuthenticationSession, share sheet, …). For these there is no
+   * meaningful deadline — a watchdog could only false-timeout mid-interaction
+   * and force a spurious fallback. Do NOT use it for fire-and-fast calls: a
+   * finite timeout is what surfaces a real native hang. */
+  timeoutMs?: number | 'none';
 }
 
 export interface NativeKitAdapter {

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

@@ -132,10 +132,9 @@ export class BillingModule {
     if (this.capability !== 'native') {
       throw new KitError('UNSUPPORTED', 'The in-app subscriptions sheet is iOS-only (StoreKit 2). Use manageSubscriptions() on web/Android.');
     }
-    // The sheet resolves only when the USER dismisses it (seconds to minutes), so the default 10s
-    // invoke timeout would fire mid-sheet and make the caller think it failed → a spurious fallback.
-    // Give it a long window; a dismissed-but-unreported sheet just leaves the promise pending (harmless).
-    return this.kit.invoke('billing.manageSubscriptionsSheet', undefined, { timeoutMs: 600_000 });
+    // Dismiss-bound: resolves only when the USER closes the sheet (no meaningful deadline).
+    // A watchdog could only false-timeout mid-sheet → spurious fallback, so disable it.
+    return this.kit.invoke('billing.manageSubscriptionsSheet', undefined, { timeoutMs: 'none' });
   }
 
   /** Out-of-band transactions (renewals, Ask-to-Buy, cross-device). Native streams only. */

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/oauth.ts

@@ -39,9 +39,9 @@ export class OAuthModule {
   }
 
   authorize(params: OAuthAuthorizeParams): Promise<OAuthResult> {
-    // Long timeout: a real sign-in (password + 2FA + consent in the system browser) easily exceeds
-    // the 10s invoke default — without this the kit abandons the request id before the redirect
-    // returns and the login is silently dropped. Matches the other interactive flows (pickers 120s).
-    return this.kit.invoke('oauth.authorize', params as unknown as Record<string, unknown>, { timeoutMs: 300_000 });
+    // Dismiss-bound: the ASWebAuthenticationSession / Custom Tab resolves only when the user
+    // finishes (password + 2FA + consent) or cancels — there is no meaningful deadline. A watchdog
+    // would abandon the request id before the redirect returns and silently drop the login.
+    return this.kit.invoke('oauth.authorize', params as unknown as Record<string, unknown>, { timeoutMs: 'none' });
   }
 }

package/src/modules/push.ts

@@ -9,6 +9,11 @@ export type PushPlatform = 'apns' | 'fcm';
 export interface PushToken {
   platform: PushPlatform;
   token: string;
+  /** The app's bundle/package id. On iOS this is the APNs `apns-topic` your backend MUST send
+   * (APNs rejects a mismatch with `DeviceTokenNotForTopic`); on Android it's the package id —
+   * informational, since FCM doesn't use apns-topic. Optional: absent on web / un-provisioned
+   * builds and older shells that don't supply it (a missing topic is tolerated). */
+  topic?: string;
 }
 
 /** A remote message surfaced to the page. `data` is the sender's custom payload; `title`/`body`
@@ -27,8 +32,9 @@ export interface PushMessage {
  * ```ts
  * if (kit.push.capability === 'native') {
  *   if (await kit.push.requestPermission() === 'granted') {
- *     const { platform, token } = await kit.push.register();
- *     await fetch('/api/push/register', { method:'POST', body: JSON.stringify({ platform, token }) });
+ *     const { platform, token, topic } = await kit.push.register();
+ *     // `topic` = the iOS bundle id → your backend sets it as the APNs apns-topic header.
+ *     await fetch('/api/push/register', { method:'POST', body: JSON.stringify({ platform, token, topic }) });
  *   }
  *   kit.push.onMessage((m) => …);   // foreground delivery
  *   kit.push.onTap((m) => …);       // user opened a notification

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');
+  }
+}