@livx.cc/native-kit 0.32.3 → 0.35.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.35.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 { AppleSignInModule } from '../modules/appleSignIn';
 import { BackgroundTaskModule } from '../modules/backgroundTask';
 import { BillingModule } from '../modules/billing/billing';
 import { BiometricsModule } from '../modules/biometrics';
@@ -30,6 +31,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 +105,8 @@ 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 readonly appleSignIn = new AppleSignInModule(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,14 @@ 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 type {
+  AppleSignInName,
+  AppleSignInParams,
+  AppleSignInResult,
+  AppleSignInCancelled,
+} from './modules/appleSignIn';
+export { isAppleSignInResult } from './modules/appleSignIn';
 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/appleSignIn.ts

@@ -0,0 +1,96 @@
+import type { NativeKit } from '../core/NativeKit';
+import { KitError } from '../core/types';
+
+/** The name Apple returns on the FIRST authorization per Apple ID (subsequent sign-ins omit it). */
+export interface AppleSignInName {
+  /** Given (first) name, when provided. */
+  givenName?: string;
+  /** Family (last) name, when provided. */
+  familyName?: string;
+  /** A display name composed by the OS from the components, when provided. */
+  displayName?: string;
+}
+
+/** A successful native Sign in with Apple. Feed `identityToken` + `nonce` (raw) to Firebase:
+ *  `signInWithCredential(OAuthProvider.credential('apple.com', { idToken: identityToken, rawNonce: nonce }))`. */
+export interface AppleSignInResult {
+  /** The Apple identity JWT (`id_token`) — what Firebase / your backend verifies. */
+  identityToken: string;
+  /** Short-lived authorization code (for an optional server-side token exchange). */
+  authorizationCode?: string;
+  /** The RAW nonce you passed in — Apple hashed SHA256(nonce); Firebase needs the raw value back. */
+  nonce: string;
+  /** First-authorization-only profile. Apple returns name/email ONLY the first time per Apple ID —
+   *  persist it on first sign-in; it is absent on every subsequent call. */
+  user?: { name?: AppleSignInName; email?: string };
+}
+
+/** Sign in resolved without a credential because the user dismissed the system sheet. */
+export interface AppleSignInCancelled {
+  cancelled: true;
+}
+
+export interface AppleSignInParams {
+  /** A RAW, cryptographically-random nonce (the caller generates it). The handler sends SHA256(nonce)
+   *  to Apple and returns this raw value so you can pass it to Firebase as `rawNonce`. Required. */
+  nonce: string;
+  /** Profile scopes to request on first authorization. Default `['name', 'email']`. */
+  scopes?: Array<'name' | 'email'>;
+}
+
+/** True when an {@link AppleSignInResult} (a credential) is present (not the cancelled shape). */
+export function isAppleSignInResult(r: AppleSignInResult | AppleSignInCancelled): r is AppleSignInResult {
+  return (r as AppleSignInCancelled).cancelled !== true;
+}
+
+/**
+ * Native Sign in with Apple — iOS `ASAuthorizationController` (the system account sheet). Returns the
+ * `identityToken` (JWT) + the raw nonce DIRECTLY to JS, so a wrapped app does true-native Apple auth and
+ * hands the result to Firebase `signInWithCredential(OAuthProvider.credential('apple.com', { idToken,
+ * rawNonce }))` — no Services ID, no https Return URL, no browser redirect, no cross-origin storage.
+ *
+ * WHY (not `kit.oauth`): the web-OAuth path (`ASWebAuthenticationSession`) needs an Apple **Services ID**
+ * with a custom-scheme `redirect_uri`, which Apple rejects (Services IDs require registered https Return
+ * URLs). The native ASAuthorization flow uses the **App ID** (bundle) and returns the token directly.
+ *
+ * Provider-agnostic, like `kit.push`/`kit.oauth`: the shell owns only the device-side primitive (present
+ * the sheet, hash the nonce, hand back the token). The PWA generates the nonce and does the Firebase
+ * `signInWithCredential` exchange.
+ *
+ * Capability gating (honest):
+ *  - iOS 13+: `'native'`.
+ *  - Android / web / iOS < 13: `'none'` — Sign in with Apple has NO native SDK off iOS. {@link signIn}
+ *    throws `UNSUPPORTED`; the PWA should fall back to its web Apple auth (Firebase popup/redirect)
+ *    when `capability !== 'native'`. Branch on {@link capability}.
+ *
+ * Cancel contract: a user-dismissed sheet RESOLVES `{ cancelled: true }` (never throws) — mirrors
+ * {@link import('./scanner').ScannerModule}. Real failures reject with a {@link import('../core/types').KitError}.
+ */
+export class AppleSignInModule {
+  constructor(private kit: NativeKit) {}
+
+  /** `'native'` on an iOS shell · `'none'` on Android/web/iOS<13. */
+  get capability() {
+    return this.kit.capability('appleSignIn');
+  }
+
+  /**
+   * Present the native Sign in with Apple sheet. Resolves an {@link AppleSignInResult} on success or
+   * `{ cancelled: true }` if the user dismisses it (branch with {@link isAppleSignInResult}).
+   *
+   * The handler hashes the supplied raw `nonce` (SHA256) before sending it to Apple and returns the
+   * RAW nonce in the result so you can pass it to Firebase as `rawNonce`.
+   *
+   * Dismiss-bound — the sheet resolves only when the user completes or cancels, so there's no watchdog
+   * timeout (a deadline would abandon the request mid-handshake). Throws `UNSUPPORTED` off iOS.
+   */
+  signIn(params: AppleSignInParams): Promise<AppleSignInResult | AppleSignInCancelled> {
+    const nonce = String(params?.nonce ?? '');
+    if (!nonce) return Promise.reject(new KitError('NATIVE_ERROR', 'appleSignIn: a raw nonce is required'));
+    if (this.capability !== 'native') {
+      return Promise.reject(new KitError('UNSUPPORTED', 'appleSignIn is iOS-only (no native Sign in with Apple off iOS)'));
+    }
+    const scopes = params.scopes ?? ['name', 'email'];
+    return this.kit.invoke('appleSignIn.signIn', { nonce, scopes }, { timeoutMs: 'none' });
+  }
+}

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