@livx.cc/native-kit 0.16.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@livx.cc/native-kit",
+  "version": "0.16.0",
+  "description": "Isomorphic native-capabilities kit for PWAs — same API in browser and in an appwrap native shell. Zero dependencies.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --format esm && bun build src/index.ts --outfile dist/native-kit.iife.js --format iife --global-name NativeKitLib"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/core/NativeKit.ts

@@ -0,0 +1,131 @@
+import { AppwrapAdapter } from './appwrap-adapter';
+import { WebAdapter } from './web-adapter';
+import { Capability, Handshake, InvokeOptions, KIT_PROTOCOL, KitError, NativeKitAdapter, Unsubscribe } from './types';
+import { AppModule } from '../modules/app';
+import { BillingModule } from '../modules/billing/billing';
+import { BiometricsModule } from '../modules/biometrics';
+import { BrowserModule } from '../modules/browser';
+import { CalendarModule } from '../modules/calendar';
+import { ClipboardModule } from '../modules/clipboard';
+import { ContactsModule } from '../modules/contacts';
+import { DeviceModule } from '../modules/device';
+import { GeoModule } from '../modules/geo';
+import { HapticsModule } from '../modules/haptics';
+import { HealthModule } from '../modules/health';
+import { LifecycleModule } from '../modules/lifecycle';
+import { MediaModule } from '../modules/media';
+import { MotionModule } from '../modules/motion';
+import { NetworkModule } from '../modules/network';
+import { NotificationsModule } from '../modules/notifications';
+import { OAuthModule } from '../modules/oauth';
+import { PhotosModule } from '../modules/photos';
+import { PushModule } from '../modules/push';
+import { ReviewsModule } from '../modules/reviews';
+import { ScreenModule } from '../modules/screen';
+import { ShareModule } from '../modules/share';
+import { StorageModule } from '../modules/storage';
+import { ToastModule } from '../modules/toast';
+import { UiModule } from '../modules/ui';
+
+export class NativeKitOptions {
+  /** Priority order; first adapter whose detect() passes wins. */
+  adapters: NativeKitAdapter[] = [new AppwrapAdapter(), new WebAdapter()];
+  handshakeTimeoutMs = 3000;
+}
+
+export class NativeKit {
+  public readonly haptics = new HapticsModule(this);
+  public readonly share = new ShareModule(this);
+  public readonly screen = new ScreenModule(this);
+  public readonly storage = new StorageModule(this);
+  public readonly toast = new ToastModule(this);
+  public readonly ui = new UiModule(this);
+  public readonly device = new DeviceModule(this);
+  public readonly clipboard = new ClipboardModule(this);
+  public readonly notifications = new NotificationsModule(this);
+  public readonly push = new PushModule(this);
+  public readonly biometrics = new BiometricsModule(this);
+  public readonly geo = new GeoModule(this);
+  public readonly photos = new PhotosModule(this);
+  public readonly network = new NetworkModule(this);
+  public readonly lifecycle = new LifecycleModule(this);
+  public readonly reviews = new ReviewsModule(this);
+  public readonly motion = new MotionModule(this);
+  public readonly health = new HealthModule(this);
+  public readonly media = new MediaModule(this);
+  public readonly contacts = new ContactsModule(this);
+  public readonly calendar = new CalendarModule(this);
+  public readonly app = new AppModule(this);
+  public readonly browser = new BrowserModule(this);
+  public readonly oauth = new OAuthModule(this);
+  public readonly billing = new BillingModule(this);
+
+  public handshakeInfo: Handshake | null = null;
+  public options: NativeKitOptions;
+  private adapter: NativeKitAdapter | null = null;
+  private readyPromise: Promise<Handshake> | null = null;
+
+  constructor(options?: Partial<NativeKitOptions>) {
+    this.options = { ...new NativeKitOptions(), ...options };
+  }
+
+  /** Resolve the environment and perform the handshake. Idempotent. */
+  ready(): Promise<Handshake> {
+    if (!this.readyPromise) {
+      this.readyPromise = (async () => {
+        const adapter = this.options.adapters.find((a) => a.detect());
+        if (!adapter) throw new KitError('NOT_READY', 'No adapter detected this environment');
+        this.adapter = adapter;
+        const handshake = await adapter.handshake(this.options.handshakeTimeoutMs);
+        // Version-skew safety net: a native shell from an older `appwrap init` may speak a
+        // different protocol. Fail loud rather than silently mis-degrade. The web adapter
+        // always reports the kit's own protocol, so this only ever fires against a stale shell.
+        if (handshake.protocol !== KIT_PROTOCOL) {
+          throw new KitError(
+            'UNSUPPORTED',
+            `Shell protocol v${handshake.protocol} ≠ kit protocol v${KIT_PROTOCOL} — ` +
+              `the native wrapper is out of date. Re-run \`appwrap init\` to regenerate it.`
+          );
+        }
+        this.handshakeInfo = handshake;
+        return this.handshakeInfo;
+      })();
+    }
+    return this.readyPromise;
+  }
+
+  get is() {
+    return { native: this.adapter?.kind === 'appwrap', web: this.adapter?.kind === 'web' };
+  }
+
+  get platform() {
+    return this.handshakeInfo?.platform ?? 'web';
+  }
+
+  capability(name: string): Capability {
+    return this.handshakeInfo?.capabilities[name] ?? 'none';
+  }
+
+  async invoke<T = unknown>(method: string, params?: unknown, opts?: InvokeOptions): Promise<T> {
+    if (!this.adapter) await this.ready();
+    return this.adapter!.invoke<T>(method, params, opts);
+  }
+
+  on(event: string, cb: (payload: unknown) => void): Unsubscribe {
+    if (!this.adapter) {
+      // Defer subscription until ready() resolves the adapter.
+      let unsub: Unsubscribe | null = null;
+      let cancelled = false;
+      this.ready()
+        .then(() => {
+          if (!cancelled) unsub = this.adapter!.on(event, cb);
+        })
+        .catch(() => {}); // ready() failure already surfaces to the ready() caller
+      return () => { cancelled = true; unsub?.(); };
+    }
+    return this.adapter.on(event, cb);
+  }
+}
+
+/** Shared default instance — `import { kit } from '@livx.cc/native-kit'`. */
+export const kit = new NativeKit();

package/src/core/appwrap-adapter.ts

@@ -0,0 +1,107 @@
+import {
+  Envelope,
+  Handshake,
+  InvokeOptions,
+  KitError,
+  NativeKitAdapter,
+  RequestEnvelope,
+  ResponseEnvelope,
+  Unsubscribe,
+} from './types';
+
+declare global {
+  interface Window {
+    webkit?: { messageHandlers?: { appwrap?: { postMessage(msg: unknown): void } } };
+    appwrapNative?: { postMessage(json: string): void };
+    __appwrapDeliver?: (json: string) => void;
+  }
+}
+
+/**
+ * Talks appwrap protocol v1 to the native shell. Envelopes travel as JSON strings
+ * in both directions (NSDictionary marshalling through WKScriptMessage is lossy in
+ * some bridges; strings are not).
+ * - web → native: iOS `webkit.messageHandlers.appwrap.postMessage(json)`,
+ *   Android `appwrapNative.postMessage(json)` (shell-injected shim or JS interface).
+ * - native → web: shell evaluates `window.__appwrapDeliver(json)`.
+ */
+export class AppwrapAdapter implements NativeKitAdapter {
+  readonly kind = 'appwrap' as const;
+  private pending = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+  private listeners = new Map<string, Set<(payload: unknown) => void>>();
+  private seq = 0;
+
+  detect(): boolean {
+    return typeof window !== 'undefined' &&
+      (!!window.webkit?.messageHandlers?.appwrap || !!window.appwrapNative);
+  }
+
+  async handshake(timeoutMs: number): Promise<Handshake> {
+    this.installDeliver();
+    return this.request<Handshake>('app.handshake', undefined, timeoutMs);
+  }
+
+  invoke<T>(method: string, params?: unknown, opts?: InvokeOptions): Promise<T> {
+    return this.request<T>(method, params, opts?.timeoutMs ?? 10_000);
+  }
+
+  on(event: string, cb: (payload: unknown) => void): Unsubscribe {
+    let set = this.listeners.get(event);
+    if (!set) this.listeners.set(event, (set = new Set()));
+    set.add(cb);
+    return () => set!.delete(cb);
+  }
+
+  private request<T>(method: string, params: unknown, timeoutMs: number): Promise<T> {
+    const id = `k${++this.seq}`;
+    const envelope: RequestEnvelope = { v: 1, id, kind: 'request', method, params };
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new KitError('TIMEOUT', `${method} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (v) => { clearTimeout(timer); resolve(v as T); },
+        reject: (e) => { clearTimeout(timer); reject(e); },
+      });
+      this.post(envelope);
+    });
+  }
+
+  private post(envelope: RequestEnvelope): void {
+    const json = JSON.stringify(envelope);
+    if (window.webkit?.messageHandlers?.appwrap) {
+      window.webkit.messageHandlers.appwrap.postMessage(json);
+    } else if (window.appwrapNative) {
+      window.appwrapNative.postMessage(json);
+    } else {
+      const p = this.pending.get(envelope.id);
+      this.pending.delete(envelope.id);
+      p?.reject(new KitError('NOT_READY', 'No native transport present'));
+    }
+  }
+
+  private installDeliver(): void {
+    if (window.__appwrapDeliver) return;
+    window.__appwrapDeliver = (json: string) => {
+      let envelope: Envelope;
+      try {
+        envelope = JSON.parse(json);
+      } catch {
+        return;
+      }
+      if (envelope.kind === 'response') this.handleResponse(envelope);
+      else if (envelope.kind === 'event') {
+        this.listeners.get(envelope.event)?.forEach((cb) => cb(envelope.payload));
+      }
+    };
+  }
+
+  private handleResponse(envelope: ResponseEnvelope): void {
+    const p = this.pending.get(envelope.id);
+    if (!p) return;
+    this.pending.delete(envelope.id);
+    if (envelope.error) p.reject(new KitError(envelope.error.code, envelope.error.message));
+    else p.resolve(envelope.result);
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,78 @@
+export type Platform = 'ios' | 'android' | 'web';
+export type AdapterKind = 'appwrap' | 'web';
+
+/** Bridge protocol version this kit speaks. The native shell reports its own in the handshake;
+ * `ready()` asserts they match so a kit running against a stale shell fails loud instead of
+ * silently mis-degrading. Bump in lockstep with a breaking change to the wire envelope. */
+export const KIT_PROTOCOL = 1 as const;
+
+/** How a capability is fulfilled in the current environment. */
+export type Capability = 'native' | 'web' | 'none';
+
+export interface AppInfo {
+  id: string;
+  name: string;
+  version: string;
+  build?: string;
+}
+
+export interface Handshake {
+  protocol: 1;
+  platform: Platform;
+  app: AppInfo;
+  capabilities: Record<string, Capability>;
+  /** Optional diagnostic payload (breadcrumbs, etc.). */
+  debug?: Record<string, unknown>;
+}
+
+/** Wire envelope (appwrap protocol v1). Web adapter never serializes these. */
+export interface RequestEnvelope {
+  v: 1;
+  id: string;
+  kind: 'request';
+  method: string;
+  params?: unknown;
+}
+
+export interface ResponseEnvelope {
+  v: 1;
+  id: string;
+  kind: 'response';
+  result?: unknown;
+  error?: { code: KitErrorCode; message: string };
+}
+
+export interface EventEnvelope {
+  v: 1;
+  kind: 'event';
+  event: string;
+  payload?: unknown;
+}
+
+export type Envelope = RequestEnvelope | ResponseEnvelope | EventEnvelope;
+
+export type KitErrorCode = 'UNSUPPORTED' | 'DENIED' | 'TIMEOUT' | 'NATIVE_ERROR' | 'NOT_READY';
+
+export class KitError extends Error {
+  constructor(public code: KitErrorCode, message: string) {
+    super(message);
+    this.name = 'KitError';
+  }
+}
+
+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;
+}
+
+export interface NativeKitAdapter {
+  readonly kind: AdapterKind;
+  /** Is this environment present? Must be cheap and side-effect free. */
+  detect(): boolean;
+  handshake(timeoutMs: number): Promise<Handshake>;
+  invoke<T = unknown>(method: string, params?: unknown, opts?: InvokeOptions): Promise<T>;
+  on(event: string, cb: (payload: unknown) => void): Unsubscribe;
+}