@livx.cc/native-kit 0.16.0

package/src/modules/network.ts

@@ -0,0 +1,24 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+export interface NetworkStatus {
+  online: boolean;
+  /** 'wifi' | 'cellular' | 'none' | 'unknown' */
+  type: string;
+}
+
+export class NetworkModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('network');
+  }
+
+  status(): Promise<NetworkStatus> {
+    return this.kit.invoke('network.status');
+  }
+
+  onChange(cb: (status: NetworkStatus) => void): Unsubscribe {
+    return this.kit.on('network.change', (p) => cb(p as NetworkStatus));
+  }
+}

package/src/modules/notifications.ts

@@ -0,0 +1,45 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export interface ScheduleOptions {
+  id?: number;
+  title: string;
+  body?: string;
+  /** Seconds from now (default 1). */
+  delaySec?: number;
+  /**
+   * Deep-link URL fired when the notification is tapped (e.g. 'app://item/7').
+   * Delivered through the same `deeplink.open` event as an external open, so
+   * `kit.lifecycle.onDeepLink` routes it with no extra wiring.
+   */
+  deepLink?: string;
+}
+
+export class NotificationsModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('notifications');
+  }
+
+  /** 'granted' | 'denied' | 'default' */
+  requestPermission(): Promise<string> {
+    return this.kit.invoke('notifications.requestPermission', undefined, { timeoutMs: 60_000 });
+  }
+
+  schedule(options: ScheduleOptions): Promise<{ id: number }> {
+    return this.kit.invoke('notifications.schedule', options);
+  }
+
+  /** Count of pending (scheduled, not yet delivered) notifications. */
+  pending(): Promise<number> {
+    return this.kit.invoke('notifications.pending');
+  }
+
+  setBadge(count: number): Promise<void> {
+    return this.kit.invoke('notifications.setBadge', { count });
+  }
+
+  clear(): Promise<void> {
+    return this.kit.invoke('notifications.clear');
+  }
+}

package/src/modules/oauth.ts

@@ -0,0 +1,41 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export interface OAuthAuthorizeParams {
+  /** Full authorization URL — provider endpoint + query (client_id, redirect_uri, scope, PKCE…). */
+  url: string;
+  /** The custom URL scheme the redirect_uri uses (e.g. 'circles' for circles://oauth). The system
+   *  browser sheet closes + returns as soon as it sees a redirect to this scheme. */
+  callbackScheme: string;
+  /** Don't persist browser cookies (fresh provider login every time). Default false — reuses the
+   *  existing provider session so the user isn't re-typing their Google password. */
+  ephemeral?: boolean;
+}
+
+export interface OAuthResult {
+  /** The full callback URL the provider redirected to, including ?code=…&state=… (or #fragment). */
+  url: string;
+}
+
+/**
+ * System-browser OAuth via ASWebAuthenticationSession (iOS). Provider-agnostic by design — the same
+ * philosophy as `kit.push`: the shell owns only the device-side primitive (run the auth handshake in
+ * the OS-shared, policy-compliant browser), while the PWA builds the auth URL and does token exchange.
+ *
+ * WHY: Google (and others) reject OAuth loaded inside an embedded WebView with
+ * `403 disallowed_useragent`. ASWebAuthenticationSession is the compliant browser, so the flow
+ * succeeds and returns the redirect to your custom scheme.
+ *
+ * Web fallback: capability is 'none' — the PWA should use its normal web OAuth (popup/redirect) when
+ * `kit.oauth.capability !== 'native'`.
+ */
+export class OAuthModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('oauth');
+  }
+
+  authorize(params: OAuthAuthorizeParams): Promise<OAuthResult> {
+    return this.kit.invoke('oauth.authorize', params as unknown as Record<string, unknown>);
+  }
+}

package/src/modules/photos.ts

@@ -0,0 +1,39 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export interface PickPhotoOptions {
+  /** Return the image as a downscaled JPEG data URL the PWA can render/upload. */
+  dataUrl?: boolean;
+  /** Longest-edge cap in px for the returned dataUrl (default 1024). */
+  maxSize?: number;
+}
+
+export interface PickedPhoto {
+  picked: boolean;
+  /** Present when picked: dimensions of the selected image. */
+  width?: number;
+  height?: number;
+  /** Present when `dataUrl` was requested: `data:image/jpeg;base64,...`. */
+  dataUrl?: string;
+}
+
+export class PhotosModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('photos');
+  }
+
+  get cameraCapability() {
+    return this.kit.capability('camera');
+  }
+
+  /** Open the system photo picker; resolves { picked: false } when dismissed. */
+  pick(options?: PickPhotoOptions): Promise<PickedPhoto> {
+    return this.kit.invoke('photos.pick', options, { timeoutMs: 120_000 });
+  }
+
+  /** Capture a photo with the camera. UNSUPPORTED where no camera exists (e.g. simulator). */
+  capture(options?: PickPhotoOptions): Promise<PickedPhoto> {
+    return this.kit.invoke('camera.capture', options, { timeoutMs: 120_000 });
+  }
+}

package/src/modules/push.ts

@@ -0,0 +1,71 @@
+import type { NativeKit } from '../core/NativeKit';
+import { KitError, type Capability, type Unsubscribe } from '../core/types';
+
+/** Which transport produced the token — the consumer's backend needs this to pick the right sender. */
+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. */
+export interface PushToken {
+  platform: PushPlatform;
+  token: string;
+}
+
+/** A remote message surfaced to the page. `data` is the sender's custom payload; `title`/`body`
+ * are present when the sender included a display (aps.alert / FCM notification). */
+export interface PushMessage {
+  data: Record<string, unknown>;
+  title?: string;
+  body?: string;
+}
+
+/**
+ * Remote push — ONE API across iOS (APNs) and Android (FCM). DEVICE SIDE ONLY:
+ * the kit acquires the token + surfaces incoming messages/taps; SENDING is your
+ * backend's job (see {@link PushToken}). Provider-agnostic by construction.
+ *
+ * ```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 }) });
+ *   }
+ *   kit.push.onMessage((m) => …);   // foreground delivery
+ *   kit.push.onTap((m) => …);       // user opened a notification
+ * }
+ * ```
+ */
+export class PushModule {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' on a push-enabled shell (APNs/FCM configured), else 'none'. Web push (VAPID)
+   * is the app's own concern — the kit reports 'none' rather than pretend to own it. */
+  get capability(): Capability {
+    return this.kit.is.native ? this.kit.capability('push') : 'none';
+  }
+
+  /** Prompt for notification authorization. 'granted' | 'denied'. */
+  requestPermission(): Promise<'granted' | 'denied'> {
+    return this.kit.invoke('push.requestPermission', undefined, { timeoutMs: 60_000 });
+  }
+
+  /** 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 });
+  }
+
+  /** Stop receiving remote pushes (iOS unregisterForRemoteNotifications / FCM deleteToken). */
+  unregister(): Promise<void> {
+    return this.kit.invoke('push.unregister');
+  }
+
+  /** Foreground message delivery (app open, no tap). */
+  onMessage(cb: (m: PushMessage) => void): Unsubscribe {
+    return this.kit.on('push.message', (p) => cb(p as PushMessage));
+  }
+
+  /** User tapped a notification — carries the same payload + drives navigation. */
+  onTap(cb: (m: PushMessage) => void): Unsubscribe {
+    return this.kit.on('push.tap', (p) => cb(p as PushMessage));
+  }
+}

package/src/modules/reviews.ts

@@ -0,0 +1,15 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/** Store review prompt — iOS SKStoreReviewController. The OS rate-limits display. */
+export class ReviewsModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('reviews');
+  }
+
+  /** Ask the OS to show the in-app review prompt. Fire-and-forget; the OS decides. */
+  requestReview(): Promise<void> {
+    return this.kit.invoke('reviews.requestReview');
+  }
+}

package/src/modules/screen.ts

@@ -0,0 +1,55 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+export type Orientation = 'portrait' | 'landscape';
+/** What to lock to. 'any' releases the lock (same as {@link OrientationController.unlock}). */
+export type OrientationLock =
+  | 'portrait'
+  | 'portrait-upside-down'
+  | 'landscape'
+  | 'landscape-left'
+  | 'landscape-right'
+  | 'any';
+
+/** Screen-level controls. Today: orientation; brightness/keepAwake live on `kit.ui`. */
+export class ScreenModule {
+  readonly orientation: OrientationController;
+
+  constructor(kit: NativeKit) {
+    this.orientation = new OrientationController(kit);
+  }
+}
+
+/**
+ * Lock/observe the device orientation — ONE API across platforms.
+ *
+ * Native pins the app (iOS supported-orientations + geometry update, Android
+ * `setRequestedOrientation`). On web the Screen Orientation API needs fullscreen
+ * and is widely unsupported (desktop, iOS Safari) — `lock` rejects with
+ * `KitError('UNSUPPORTED')` there; gate on {@link capability} or catch it.
+ */
+export class OrientationController {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' on a shell · 'web' where the Screen Orientation API exists · else 'none'. */
+  get capability() {
+    return this.kit.capability('orientation');
+  }
+
+  lock(orientation: OrientationLock): Promise<void> {
+    return this.kit.invoke('screen.orientation.lock', { orientation });
+  }
+
+  /** Release the lock (rotate freely again). */
+  unlock(): Promise<void> {
+    return this.kit.invoke('screen.orientation.unlock');
+  }
+
+  current(): Promise<Orientation> {
+    return this.kit.invoke('screen.orientation.current');
+  }
+
+  onChange(cb: (orientation: Orientation) => void): Unsubscribe {
+    return this.kit.on('screen.orientation.change', (p) => cb(p as Orientation));
+  }
+}

package/src/modules/share.ts

@@ -0,0 +1,37 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export interface SharePayload {
+  title?: string;
+  text?: string;
+  url?: string;
+}
+
+/** A file to share. `base64` is raw base64 (no `data:` prefix) — JSON-safe over the bridge. */
+export interface ShareFile {
+  name: string; // filename incl. extension, e.g. 'invoice.pdf'
+  mimeType: string; // e.g. 'application/pdf', 'image/png'
+  base64: string;
+}
+
+export class ShareModule {
+  constructor(private kit: NativeKit) {}
+
+  /** Text/url share — iOS share sheet, Android chooser, web `navigator.share`. */
+  get capability() {
+    return this.kit.capability('share');
+  }
+
+  /** File share — distinct flag (a platform can share text but not files). */
+  get filesCapability() {
+    return this.kit.capability('shareFiles');
+  }
+
+  share(payload: SharePayload): Promise<void> {
+    return this.kit.invoke('share.share', payload);
+  }
+
+  /** Share one or more files (iOS UIActivity / web `navigator.share({files})`). */
+  files(files: ShareFile[], opts?: { title?: string; text?: string }): Promise<void> {
+    return this.kit.invoke('share.files', { files, ...opts });
+  }
+}

package/src/modules/storage.ts

@@ -0,0 +1,55 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/**
+ * Secure KV — native: Keychain/Keystore. No web fallback (capability 'none');
+ * localStorage is not a secret store.
+ */
+export class SecureStorage {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('secureStorage');
+  }
+
+  get(key: string): Promise<string | null> {
+    return this.kit.invoke('storage.secure.get', { key });
+  }
+
+  set(key: string, value: string): Promise<void> {
+    return this.kit.invoke('storage.secure.set', { key, value });
+  }
+
+  remove(key: string): Promise<void> {
+    return this.kit.invoke('storage.secure.remove', { key });
+  }
+}
+
+/** Simple KV storage. Native: ApplicationSettings (survives WebView data clears). Web: localStorage. */
+export class StorageModule {
+  public readonly secure: SecureStorage;
+
+  constructor(private kit: NativeKit) {
+    this.secure = new SecureStorage(kit);
+  }
+
+  get capability() {
+    return this.kit.capability('storage');
+  }
+
+  get<T = unknown>(key: string): Promise<T | null> {
+    return this.kit.invoke('storage.get', { key });
+  }
+
+  set(key: string, value: unknown): Promise<void> {
+    return this.kit.invoke('storage.set', { key, value });
+  }
+
+  remove(key: string): Promise<void> {
+    return this.kit.invoke('storage.remove', { key });
+  }
+
+  /** Remove every kit-stored key (does not touch the secure store). */
+  clear(): Promise<void> {
+    return this.kit.invoke('storage.clear');
+  }
+}

package/src/modules/toast.ts

@@ -0,0 +1,13 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export class ToastModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('toast');
+  }
+
+  show(message: string, duration: 'short' | 'long' = 'short'): Promise<void> {
+    return this.kit.invoke('toast.show', { message, duration });
+  }
+}

package/src/modules/ui.ts

@@ -0,0 +1,135 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+export interface SafeAreaInsets {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+export interface AlertOptions {
+  title?: string;
+  message: string;
+  ok?: string;
+}
+
+export interface ConfirmOptions {
+  title?: string;
+  message: string;
+  ok?: string;
+  cancel?: string;
+}
+
+export interface ActionOptions {
+  title?: string;
+  options: string[];
+  cancel?: string;
+}
+
+/** Perceived-luminance test for #rgb / #rrggbb — true when the color is light. */
+function isLightColor(hex: string): boolean {
+  const m = hex.trim().replace('#', '');
+  const full = m.length === 3 ? m.split('').map((c) => c + c).join('') : m;
+  if (full.length < 6) return false;
+  const r = parseInt(full.slice(0, 2), 16);
+  const g = parseInt(full.slice(2, 4), 16);
+  const b = parseInt(full.slice(4, 6), 16);
+  // Rec. 601 luma; >0.6 reads as a light surface needing dark icons.
+  return (0.299 * r + 0.587 * g + 0.114 * b) / 255 > 0.6;
+}
+
+export class UiModule {
+  constructor(private kit: NativeKit) {}
+
+  get statusBarCapability() {
+    return this.kit.capability('statusBar');
+  }
+
+  get screenCapability() {
+    return this.kit.capability('screen');
+  }
+
+  get dialogsCapability() {
+    return this.kit.capability('dialogs');
+  }
+
+  get themeColorCapability() {
+    return this.kit.capability('themeColor');
+  }
+
+  /** 'light' = white icons (dark backgrounds), 'dark' = black icons. */
+  setStatusBarStyle(style: 'light' | 'dark'): Promise<void> {
+    return this.kit.invoke('ui.statusBar.setStyle', { style });
+  }
+
+  safeArea(): Promise<SafeAreaInsets> {
+    return this.kit.invoke('ui.safeArea');
+  }
+
+  /** 0..1 */
+  getBrightness(): Promise<number> {
+    return this.kit.invoke('ui.brightness.get');
+  }
+
+  setBrightness(level: number): Promise<void> {
+    return this.kit.invoke('ui.brightness.set', { level });
+  }
+
+  /** Prevent the screen from sleeping. */
+  keepAwake(on: boolean): Promise<void> {
+    return this.kit.invoke('ui.keepAwake', { on });
+  }
+
+  // ── dialogs ──────────────────────────────────────────────────────────
+
+  alert(opts: AlertOptions): Promise<void> {
+    return this.kit.invoke('ui.alert', opts, { timeoutMs: 120_000 });
+  }
+
+  /** Resolves true on OK, false on cancel. */
+  confirm(opts: ConfirmOptions): Promise<boolean> {
+    return this.kit.invoke('ui.confirm', opts, { timeoutMs: 120_000 });
+  }
+
+  /** Action sheet — resolves the chosen option's index, or null on cancel. */
+  action(opts: ActionOptions): Promise<number | null> {
+    return this.kit.invoke('ui.action', opts, { timeoutMs: 120_000 });
+  }
+
+  // ── theme color ──────────────────────────────────────────────────────
+
+  /** Tint the native chrome behind the page (status bar / safe areas). */
+  setBackgroundColor(color: string): Promise<void> {
+    return this.kit.invoke('ui.setBackgroundColor', { color });
+  }
+
+  /**
+   * Keep the native chrome in sync with `<meta name="theme-color">`.
+   * Applies the current value immediately and observes changes: tints the
+   * native root (visible during launch / rotation / keyboard gaps) AND flips
+   * the status-bar icon style to keep contrast against the theme color.
+   * No-op on web — the browser honors the meta tag natively.
+   */
+  syncThemeColor(): Unsubscribe {
+    if (this.themeColorCapability !== 'native') return () => {};
+    const apply = () => {
+      const meta = document.querySelector<HTMLMetaElement>('meta[name="theme-color"]');
+      if (!meta?.content) return;
+      this.setBackgroundColor(meta.content).catch((e) =>
+        console.warn('[native-kit] setBackgroundColor failed', e)
+      );
+      // Light theme color → dark icons; dark theme color → light icons.
+      this.setStatusBarStyle(isLightColor(meta.content) ? 'dark' : 'light').catch(() => {});
+    };
+    apply();
+    const observer = new MutationObserver(apply);
+    observer.observe(document.head, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ['content'],
+    });
+    return () => observer.disconnect();
+  }
+}