@livx.cc/native-kit 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.23.0",
+  "version": "0.24.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

@@ -23,6 +23,7 @@ import { OAuthModule } from '../modules/oauth';
 import { PhotosModule } from '../modules/photos';
 import { PushModule } from '../modules/push';
 import { ReviewsModule } from '../modules/reviews';
+import { ScannerModule } from '../modules/scanner';
 import { ScreenModule } from '../modules/screen';
 import { ShareModule } from '../modules/share';
 import { StorageModule } from '../modules/storage';
@@ -91,6 +92,7 @@ export class NativeKit {
   public readonly health = new HealthModule(this);
   public readonly media = new MediaModule(this);
   public readonly contacts = new ContactsModule(this);
+  public readonly scanner = new ScannerModule(this);
   public readonly calendar = new CalendarModule(this);
   public readonly app = new AppModule(this);
   public readonly browser = new BrowserModule(this);

package/src/core/web-adapter.ts

@@ -38,6 +38,8 @@ 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;
+  /** Tear-down for an in-progress scanner.scan loop (stops the camera, removes the overlay). */
+  private scanCancel: (() => void) | null = null;
 
   detect(): boolean {
     return typeof window !== 'undefined';
@@ -75,6 +77,8 @@ export class WebAdapter implements NativeKitAdapter {
       calendar: 'none',
       camera: 'web', // <input capture> — mobile browsers open the camera
       media: (navigator as any).mediaDevices?.getUserMedia ? 'web' : 'none',
+      // BarcodeDetector (Chrome/Android) decodes; needs a getUserMedia stream to feed it. Both → 'web'.
+      scanner: typeof (window as any).BarcodeDetector !== 'undefined' && (navigator as any).mediaDevices?.getUserMedia ? 'web' : 'none',
       app: 'web', // openUrl via window.open; openSettings unsupported
       browser: 'web', // new tab/window
       billing: 'none', // no IAP in a plain browser — wire a web checkout yourself
@@ -321,6 +325,12 @@ export class WebAdapter implements NativeKitAdapter {
       case 'calendar.createEvent':
         throw new KitError('UNSUPPORTED', 'No calendar access on web');
 
+      case 'scanner.scan':
+        return this.scanBarcode(p.formats, p.camera === 'front' ? 'user' : 'environment') as Promise<T>;
+      case 'scanner.cancel':
+        this.scanCancel?.();
+        return undefined as T;
+
       case 'photos.pick':
         return this.pickImageFile(false, !!p.dataUrl, p.maxSize) as Promise<T>;
       case 'camera.capture':
@@ -447,6 +457,96 @@ export class WebAdapter implements NativeKitAdapter {
     this.listeners.get(event)?.forEach((cb) => cb(payload));
   }
 
+  /** Map our small format enum → BarcodeDetector `formats` strings. Omit/`'all'` = detector default. */
+  private toDetectorFormats(formats?: string | string[]): string[] | undefined {
+    const want = (Array.isArray(formats) ? formats : formats ? [formats] : []).filter((f) => f && f !== 'all');
+    if (!want.length) return undefined;
+    const map: Record<string, string> = { qr: 'qr_code', ean13: 'ean_13', code128: 'code_128' };
+    return want.map((f) => map[f] ?? f);
+  }
+
+  /** Reverse map a detector format string → our enum (best-effort). */
+  private fromDetectorFormat(f: string): 'qr' | 'ean13' | 'code128' | 'unknown' {
+    if (f === 'qr_code') return 'qr';
+    if (f === 'ean_13') return 'ean13';
+    if (f === 'code_128') return 'code128';
+    return 'unknown';
+  }
+
+  /**
+   * Open a full-screen camera overlay, run a BarcodeDetector loop, resolve the FIRST hit then tear
+   * down. Resolves `{ cancelled: true }` if the user taps the close button or `scanner.cancel` fires.
+   */
+  private scanBarcode(
+    formats: string | string[] | undefined,
+    facingMode: 'environment' | 'user'
+  ): Promise<{ value: string; format: string; bounds?: any } | { cancelled: true }> {
+    const Detector = (window as any).BarcodeDetector;
+    const getUserMedia = (navigator as any).mediaDevices?.getUserMedia?.bind((navigator as any).mediaDevices);
+    if (!Detector || !getUserMedia) throw new KitError('UNSUPPORTED', 'BarcodeDetector / camera unavailable in this browser');
+
+    return new Promise(async (resolve, reject) => {
+      let stream: MediaStream | null = null;
+      let raf = 0;
+      let done = false;
+      const wrap = document.createElement('div');
+      const video = document.createElement('video');
+
+      const teardown = () => {
+        if (done) return;
+        done = true;
+        cancelAnimationFrame(raf);
+        stream?.getTracks().forEach((t) => t.stop());
+        wrap.remove();
+        // Only clear if it's still OUR handler — a newer scan may have replaced it.
+        if (this.scanCancel === cancelHandler) this.scanCancel = null;
+      };
+      const cancelHandler = () => { teardown(); resolve({ cancelled: true }); };
+      this.scanCancel = cancelHandler;
+
+      try {
+        const detector = new Detector(this.toDetectorFormats(formats) ? { formats: this.toDetectorFormats(formats) } : undefined);
+        stream = await getUserMedia({ video: { facingMode } });
+        wrap.style.cssText = 'position:fixed;inset:0;background:#000;z-index:99999;display:flex;flex-direction:column';
+        video.setAttribute('playsinline', '');
+        video.muted = true;
+        video.style.cssText = 'flex:1;width:100%;height:100%;object-fit:cover';
+        (video as any).srcObject = stream;
+        const close = document.createElement('button');
+        close.textContent = 'Cancel';
+        close.style.cssText = 'position:absolute;top:max(12px,env(safe-area-inset-top));right:16px;z-index:1;background:rgba(0,0,0,.5);color:#fff;border:0;border-radius:18px;padding:8px 16px;font:15px system-ui';
+        close.onclick = () => { teardown(); resolve({ cancelled: true }); };
+        wrap.appendChild(video);
+        wrap.appendChild(close);
+        document.body.appendChild(wrap);
+        await video.play();
+
+        const tick = async () => {
+          if (done) return;
+          try {
+            const codes = await detector.detect(video);
+            if (codes?.length) {
+              const c = codes[0];
+              const b = c.boundingBox;
+              teardown();
+              resolve({
+                value: c.rawValue,
+                format: this.fromDetectorFormat(c.format),
+                bounds: b ? { x: b.x, y: b.y, width: b.width, height: b.height } : undefined,
+              });
+              return;
+            }
+          } catch { /* transient detect error — keep looping */ }
+          raf = requestAnimationFrame(tick);
+        };
+        raf = requestAnimationFrame(tick);
+      } catch (e: any) {
+        teardown();
+        reject(new KitError(e?.name === 'NotAllowedError' ? 'DENIED' : 'NATIVE_ERROR', e?.message ?? 'scan failed'));
+      }
+    });
+  }
+
   private pickImageFile(
     capture: boolean,
     wantDataUrl = false,

package/src/index.ts

@@ -35,6 +35,8 @@ export type { ActionOptions, AlertOptions, ConfirmOptions, SafeAreaInsets } from
 export type { MotionSample } from './modules/motion';
 export type { UpdateStatus, UpdatesOptions } from './modules/updates';
 export type { PickedContact } from './modules/contacts';
+export type { ScanFormat, ScanOptions, ScanResult, ScanCancelled } from './modules/scanner';
+export { isScanResult } from './modules/scanner';
 export type { CalendarEventOptions } from './modules/calendar';
 export type { BrowserOptions } from './modules/browser';
 export type { OAuthAuthorizeParams, OAuthResult } from './modules/oauth';

package/src/modules/scanner.ts

@@ -0,0 +1,63 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/** Symbologies the scanner can decode. `'all'` (default) accepts every supported format. */
+export type ScanFormat = 'qr' | 'ean13' | 'code128' | 'all';
+
+/** A successfully decoded code. */
+export interface ScanResult {
+  /** Decoded payload (the string the barcode/QR encodes). */
+  value: string;
+  /** Detected symbology — one of {@link ScanFormat} minus `'all'`, or `'unknown'`. */
+  format: ScanFormat | 'unknown';
+  /** Bounding box of the code in the camera preview (CSS px), when the platform reports it. */
+  bounds?: { x: number; y: number; width: number; height: number };
+}
+
+/** Scan resolved without a code because the user dismissed the scanner. */
+export interface ScanCancelled {
+  cancelled: true;
+}
+
+export interface ScanOptions {
+  /** Symbology filter — a single format or a list. Omit / `'all'` = any supported code. */
+  formats?: ScanFormat | ScanFormat[];
+  /** Which camera to open. Default `'back'`. */
+  camera?: 'back' | 'front';
+}
+
+/** True when a {@link ScanResult.value} is present (not the cancelled shape). */
+export function isScanResult(r: ScanResult | ScanCancelled): r is ScanResult {
+  return (r as ScanCancelled).cancelled !== true;
+}
+
+/**
+ * Camera barcode / QR decoding — ONE API across platforms.
+ *
+ * {@link scan} opens a native full-screen capture UI, returns the FIRST decoded code, then
+ * auto-dismisses. If the user dismisses it first, it resolves to `{ cancelled: true }` (NOT a
+ * rejection) — branch with {@link isScanResult}. {@link cancel} dismisses an in-progress scan
+ * programmatically, which makes that same pending {@link scan} resolve `{ cancelled: true }`.
+ *
+ * Native (iOS `AVCaptureMetadataOutput`, Android ZXing capture Activity) reports
+ * `capability === 'native'`. Web maps to the `BarcodeDetector` API where present (Chrome/Android
+ * → `'web'`); where absent (Safari/Firefox today) it's `'none'` and {@link scan} throws
+ * `KitError('UNSUPPORTED')` — no heavy JS decoder fallback. Branch on {@link capability}.
+ */
+export class ScannerModule {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' on a shell · 'web' where BarcodeDetector exists · else 'none'. */
+  get capability() {
+    return this.kit.capability('scanner');
+  }
+
+  /** Open the scanner; resolve the first code, or `{ cancelled: true }` if dismissed. */
+  scan(opts: ScanOptions = {}): Promise<ScanResult | ScanCancelled> {
+    return this.kit.invoke('scanner.scan', opts);
+  }
+
+  /** Dismiss an in-progress {@link scan} (its promise then resolves `{ cancelled: true }`). */
+  cancel(): Promise<void> {
+    return this.kit.invoke('scanner.cancel');
+  }
+}