@livx.cc/native-kit 0.37.0 → 0.39.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, tracking (iOS App Tracking Transparency), and more.
+Covers haptics, share, storage, notifications, OAuth, billing (IAP), health, geo, heading (compass), 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.37.0",
+  "version": "0.39.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

@@ -13,6 +13,7 @@ import { ContactsModule } from '../modules/contacts';
 import { DeviceModule } from '../modules/device';
 import { FsModule } from '../modules/fs';
 import { GeoModule } from '../modules/geo';
+import { HeadingModule } from '../modules/heading';
 import { HapticsModule } from '../modules/haptics';
 import { HealthModule } from '../modules/health';
 import { KeyboardModule } from '../modules/keyboard';
@@ -89,6 +90,7 @@ export class NativeKit {
   public readonly push = new PushModule(this);
   public readonly biometrics = new BiometricsModule(this);
   public readonly geo = new GeoModule(this);
+  public readonly heading = new HeadingModule(this);
   public readonly photos = new PhotosModule(this);
   public readonly network = new NetworkModule(this);
   public readonly lifecycle = new LifecycleModule(this);

package/src/core/web-adapter.ts

@@ -53,6 +53,10 @@ export class WebAdapter implements NativeKitAdapter {
   private listeners = new Map<string, Set<(payload: unknown) => void>>();
   private geoWatchId: number | null = null;
   private motionHandler: ((e: DeviceMotionEvent) => void) | null = null;
+  private headingHandler: ((e: DeviceOrientationEvent) => void) | null = null;
+  /** the orientation event actually feeding headingHandler ('deviceorientationabsolute' on Android,
+   * 'deviceorientation' on iOS via webkitCompassHeading) — remembered so stop removes the right one. */
+  private headingEvent: 'deviceorientation' | 'deviceorientationabsolute' | null = null;
   /** Tear-down for an in-progress scanner.scan loop (stops the camera, removes the overlay). */
   private scanCancel: (() => void) | null = null;
   /** Stop an in-progress speech.listen session (resolves it with the best transcript so far). */
@@ -90,6 +94,7 @@ export class WebAdapter implements NativeKitAdapter {
       reviews: 'none',
       themeColor: 'web', // the browser honors <meta name="theme-color"> itself
       motion: typeof DeviceMotionEvent !== 'undefined' ? 'web' : 'none',
+      heading: typeof DeviceOrientationEvent !== 'undefined' ? 'web' : 'none',
       contacts: n.contacts?.select ? 'web' : 'none',
       calendar: 'none',
       camera: 'web', // <input capture> — mobile browsers open the camera
@@ -343,6 +348,52 @@ export class WebAdapter implements NativeKitAdapter {
         }
         return undefined as T;
 
+      case 'heading.start': {
+        if (typeof DeviceOrientationEvent === 'undefined') throw new KitError('UNSUPPORTED', 'No orientation sensor on this browser');
+        // iOS Safari gates DeviceOrientation behind the same explicit permission prompt as motion.
+        const req = (DeviceOrientationEvent as unknown as DeviceOrientationEventWithPermission).requestPermission;
+        if (req) {
+          const state = await req().catch((e: Error) => { throw new KitError('DENIED', e.message); });
+          if (state !== 'granted') throw new KitError('DENIED', 'Orientation permission not granted');
+        }
+        if (!this.headingHandler) {
+          const hz = Math.min(60, Math.max(1, Number(p.hz) || 10));
+          const minMs = 1000 / hz;
+          let last = 0;
+          this.headingHandler = (e) => {
+            const now = performance.now();
+            if (now - last < minMs) return;
+            // iOS: webkitCompassHeading is already a TRUE 0–360 compass heading (clockwise from north).
+            // Android/standard: `deviceorientationabsolute`'s alpha is 0–360 counter-clockwise from
+            // north, so the compass heading is (360 − alpha). `e.absolute` guards against a relative
+            // reading that isn't north-referenced (useless as a compass).
+            let deg: number | null = null;
+            let accuracy: number | undefined;
+            if (typeof e.webkitCompassHeading === 'number') {
+              deg = e.webkitCompassHeading;
+              accuracy = e.webkitCompassAccuracy != null ? Math.abs(e.webkitCompassAccuracy) : undefined;
+            } else if (e.absolute && typeof e.alpha === 'number') {
+              deg = 360 - e.alpha; // normalized to [0,360) once at emit below
+            }
+            if (deg == null) return; // non-absolute reading — not a usable compass heading
+            last = now;
+            this.emit('heading.data', { deg: ((deg % 360) + 360) % 360, accuracy });
+          };
+          // Prefer the north-referenced 'deviceorientationabsolute' (Android/Chrome); fall back to
+          // 'deviceorientation' (iOS delivers webkitCompassHeading there — no absolute event).
+          this.headingEvent = 'ondeviceorientationabsolute' in window ? 'deviceorientationabsolute' : 'deviceorientation';
+          window.addEventListener(this.headingEvent, this.headingHandler as EventListener);
+        }
+        return undefined as T;
+      }
+      case 'heading.stop':
+        if (this.headingHandler && this.headingEvent) {
+          window.removeEventListener(this.headingEvent, this.headingHandler as EventListener);
+          this.headingHandler = null;
+          this.headingEvent = null;
+        }
+        return undefined as T;
+
       case 'contacts.pick': {
         const select = navigator.contacts?.select;
         if (!select) throw new KitError('UNSUPPORTED', 'Contact Picker API unavailable');

package/src/index.ts

@@ -28,6 +28,7 @@ export type { DeviceInfo } from './modules/device';
 export type { ScheduleOptions } from './modules/notifications';
 export type { PushMessage, PushPlatform, PushToken } from './modules/push';
 export type { GeoPosition } from './modules/geo';
+export type { HeadingSample } from './modules/heading';
 export type { PickedPhoto, PickPhotoOptions } from './modules/photos';
 export type { AudioMode, MediaDeviceLite, AudioState } from './modules/media';
 export type { NetworkStatus } from './modules/network';
@@ -64,4 +65,6 @@ export type {
   ProductType,
   PurchaseReceipt,
   PurchaseResult,
+  ReceiptEntitlements,
+  ReceiptOutcome,
 } from './modules/billing/types';

package/src/modules/billing/billing.ts

@@ -1,7 +1,16 @@
 import type { NativeKit } from '../../core/NativeKit';
 import { KitError, type Capability, type Unsubscribe } from '../../core/types';
 import { ClientTrustedValidator } from './validators';
-import type { BillingProvider, BillingValidator, Entitlement, Product, PurchaseReceipt, PurchaseResult } from './types';
+import type {
+  BillingProvider,
+  BillingValidator,
+  Entitlement,
+  Product,
+  PurchaseReceipt,
+  PurchaseResult,
+  ReceiptEntitlements,
+  ReceiptOutcome,
+} from './types';
 
 /**
  * In-app purchases & subscriptions — ONE API across web and native.
@@ -89,14 +98,29 @@ export class BillingModule {
    * Native iOS only, and only meaningful with a **server validator** (the bare receipt has no
    * product id — a client-trusted validator can't interpret it). Resolves `[]` on the web,
    * on Android (no StoreKit-1 receipt), or when no receipt is present (e.g. a dev build).
+   *
+   * The `[]` is AMBIGUOUS by design-history: it means both "no entitlements" and "never even
+   * asked". Use {@link receiptEntitlements} to tell those apart.
    */
   async entitlementsFromReceipt(): Promise<Entitlement[]> {
+    return (await this.receiptEntitlements()).entitlements;
+  }
+
+  /**
+   * {@link entitlementsFromReceipt} plus **why** — the same check, but the three
+   * didn't-even-ask paths are reported instead of being flattened into `[]`. See
+   * {@link ReceiptOutcome}: only `'validated'` makes an empty list a real answer.
+   *
+   * A validator that errors (network, Apple status 21004, …) REJECTS rather than
+   * reporting an outcome — a failed check is not a verdict about the user.
+   */
+  async receiptEntitlements(): Promise<ReceiptEntitlements> {
     await this.kit.ready();
-    if (this.capability !== 'native') return []; // web, or a shell with no native store handler (Android today)
-    if (this.validator instanceof ClientTrustedValidator) return []; // bare receipt has no product id → would grant a bogus active entitlement; needs a server validator
+    if (this.capability !== 'native') return { entitlements: [], outcome: 'not-native' }; // web, or a shell with no native store handler (Android today)
+    if (this.validator instanceof ClientTrustedValidator) return { entitlements: [], outcome: 'no-validator' }; // bare receipt has no product id → would grant a bogus active entitlement; needs a server validator
     const receipt = await this.kit.invoke<PurchaseReceipt>('billing.appReceipt');
-    if (!receipt?.appReceipt) return [];
-    return this.validator.validate(receipt); // server-of-record turns the receipt into entitlements
+    if (!receipt?.appReceipt) return { entitlements: [], outcome: 'no-receipt' };
+    return { entitlements: await this.validator.validate(receipt), outcome: 'validated' }; // server-of-record turns the receipt into entitlements
   }
 
   /** Current entitlements from the configured server-of-record (web provider or validator). */

package/src/modules/billing/types.ts

@@ -58,6 +58,27 @@ export interface PurchaseResult {
   entitlements: Entitlement[];
 }
 
+/**
+ * Why a receipt check produced what it did — the four outcomes that `Entitlement[]`
+ * alone collapses into an indistinguishable `[]`.
+ *
+ * - `validated`   the server-of-record read the receipt; `entitlements` is its verdict
+ *                 (still `[]` when the user genuinely owns nothing — the only outcome
+ *                 where an empty list is an ANSWER rather than a non-answer).
+ * - `not-native`  web, or a shell with no native store handler (Android: no StoreKit-1 receipt).
+ * - `no-validator` only a {@link ClientTrustedValidator} is wired; a bare app receipt carries no
+ *                 product id, so trusting it would grant a bogus entitlement. Wire a server validator.
+ * - `no-receipt`  this build has no App Store receipt. StoreKit only issues one after a purchase or
+ *                 restore, so locally-installed dev builds legitimately have none.
+ */
+export type ReceiptOutcome = 'validated' | 'not-native' | 'no-validator' | 'no-receipt';
+
+/** The outcome-carrying result of {@link BillingModule.receiptEntitlements}. */
+export interface ReceiptEntitlements {
+  entitlements: Entitlement[];
+  outcome: ReceiptOutcome;
+}
+
 /**
  * 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

package/src/modules/heading.ts

@@ -0,0 +1,38 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+export interface HeadingSample {
+  /** Compass heading in degrees, 0–360 (0 = north, 90 = east). */
+  deg: number;
+  /** Heading accuracy in degrees (± this many deg), when the platform reports it. */
+  accuracy?: number;
+}
+
+export class HeadingModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('heading');
+  }
+
+  /** Stream compass heading updates; resolves an unsubscribe once streaming starts. Requests
+   * sensor permission (iOS gesture gate) on first use. Mirrors {@link MotionModule.watch}. */
+  async watch(cb: (sample: HeadingSample) => void, opts?: { hz?: number }): Promise<Unsubscribe> {
+    const off = this.kit.on('heading.data', (p) => cb(p as HeadingSample));
+    try {
+      await this.kit.invoke('heading.start', opts?.hz ? { hz: opts.hz } : undefined);
+    } catch (e) {
+      off();
+      throw e;
+    }
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      off();
+      this.kit
+        .invoke('heading.stop')
+        .catch((e) => console.warn('[native-kit] heading.stop failed', e));
+    };
+  }
+}

package/src/web-experimental.d.ts

@@ -84,4 +84,16 @@ declare global {
   interface DeviceMotionEventWithPermission {
     requestPermission?(): Promise<'granted' | 'denied' | 'prompt'>;
   }
+
+  /** iOS Safari gates DeviceOrientation behind the same static permission prompt as DeviceMotion. */
+  interface DeviceOrientationEventWithPermission {
+    requestPermission?(): Promise<'granted' | 'denied' | 'prompt'>;
+  }
+
+  /** iOS exposes a true compass heading (0–360, magnetic north) on the orientation event — a
+   * non-standard field the lib doesn't declare. Merge it on (plus its accuracy). */
+  interface DeviceOrientationEvent {
+    webkitCompassHeading?: number;
+    webkitCompassAccuracy?: number;
+  }
 }