@livx.cc/native-kit 0.22.0 → 0.23.0

package/package.json

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

@@ -9,6 +9,7 @@ import { CalendarModule } from '../modules/calendar';
 import { ClipboardModule } from '../modules/clipboard';
 import { ContactsModule } from '../modules/contacts';
 import { DeviceModule } from '../modules/device';
+import { FsModule } from '../modules/fs';
 import { GeoModule } from '../modules/geo';
 import { HapticsModule } from '../modules/haptics';
 import { HealthModule } from '../modules/health';
@@ -73,6 +74,7 @@ export class NativeKit {
   public readonly screen = new ScreenModule(this);
   public readonly keyboard = new KeyboardModule(this);
   public readonly storage = new StorageModule(this);
+  public readonly fs = new FsModule(this);
   public readonly toast = new ToastModule(this);
   public readonly ui = new UiModule(this);
   public readonly device = new DeviceModule(this);

package/src/core/web-adapter.ts

@@ -8,6 +8,14 @@ function base64ToBuffer(b64: string): ArrayBuffer {
   return out.buffer;
 }
 
+/** Encode an ArrayBuffer → raw base64 (no `data:` prefix). */
+function bufferToBase64(buf: ArrayBuffer): string {
+  const bytes = new Uint8Array(buf);
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+
 /** Map our lock vocabulary to valid ScreenOrientation `OrientationLockType` values. */
 function toWebOrientation(o: string): any {
   switch (o) {
@@ -44,6 +52,9 @@ export class WebAdapter implements NativeKitAdapter {
       orientation: (screen as any)?.orientation ? 'web' : 'none', // Screen Orientation API (lock needs fullscreen)
       storage: 'web',
       secureStorage: 'none',
+      // OPFS (navigator.storage.getDirectory) backs read/write/list; pickFile falls back to
+      // <input type=file> even without OPFS, so 'web' whenever either surface exists.
+      fs: n.storage?.getDirectory || typeof document !== 'undefined' ? 'web' : 'none',
       toast: 'web',
       statusBar: 'none',
       device: 'web',
@@ -315,6 +326,26 @@ export class WebAdapter implements NativeKitAdapter {
       case 'camera.capture':
         return this.pickImageFile(true, !!p.dataUrl, p.maxSize) as Promise<T>;
 
+      case 'fs.read':
+        return this.opfsRead(p.path, p.encoding === 'base64' ? 'base64' : 'utf8') as Promise<T>;
+      case 'fs.write':
+        return this.opfsWrite(p.path, p.data, p.encoding === 'base64' ? 'base64' : 'utf8', false, !!p.recursive) as Promise<T>;
+      case 'fs.append':
+        return this.opfsWrite(p.path, p.data, p.encoding === 'base64' ? 'base64' : 'utf8', true, true) as Promise<T>;
+      case 'fs.delete':
+        return this.opfsDelete(p.path) as Promise<T>;
+      case 'fs.list':
+        return this.opfsList(p.path) as Promise<T>;
+      case 'fs.mkdir':
+        return this.opfsMkdir(p.path) as Promise<T>;
+      case 'fs.stat':
+        return this.opfsStat(p.path) as Promise<T>;
+      case 'fs.getUri':
+        // OPFS files have no URL the page can hand around — be honest rather than fake one.
+        throw new KitError('UNSUPPORTED', 'No file URI on web (OPFS is opaque) — read the bytes instead');
+      case 'fs.pickFile':
+        return this.pickDocuments(p.types, !!p.multiple) as Promise<T>;
+
       case 'media.configureAudio':
         return undefined as T; // browser owns the audio session — nothing to tune
 
@@ -455,6 +486,105 @@ export class WebAdapter implements NativeKitAdapter {
     });
   }
 
+  // ── filesystem (Origin Private File System) ─────────────────────────
+  // OPFS is one private root per origin — our `dir` enum has no meaning here, so paths resolve
+  // straight off the root. Slash-separated paths walk nested dirs.
+
+  private async opfsRoot(): Promise<any> {
+    const dir = (navigator as any).storage?.getDirectory;
+    if (!dir) throw new KitError('UNSUPPORTED', 'No OPFS in this browser');
+    return (navigator as any).storage.getDirectory();
+  }
+
+  /** Split a path into clean segments, rejecting any `..` so it can't escape the OPFS root. */
+  private opfsSegments(path: string): string[] {
+    const parts = String(path).split('/').filter(Boolean);
+    if (parts.some((seg) => seg === '..')) throw new KitError('NATIVE_ERROR', `Path traversal rejected: ${path}`);
+    return parts;
+  }
+
+  /** Walk `path` to its parent dir handle + leaf name. `create` makes intermediate dirs. */
+  private async opfsResolveParent(path: string, create: boolean): Promise<{ parent: any; name: string }> {
+    const parts = this.opfsSegments(path);
+    const name = parts.pop();
+    if (!name) throw new KitError('NATIVE_ERROR', 'Empty path');
+    let dir = await this.opfsRoot();
+    for (const seg of parts) dir = await dir.getDirectoryHandle(seg, { create });
+    return { parent: dir, name };
+  }
+
+  private async opfsRead(path: string, encoding: 'utf8' | 'base64'): Promise<string> {
+    const { parent, name } = await this.opfsResolveParent(path, false);
+    const handle = await parent.getFileHandle(name).catch(() => { throw new KitError('NATIVE_ERROR', `No such file: ${path}`); });
+    const file = await handle.getFile();
+    if (encoding === 'base64') return bufferToBase64(await file.arrayBuffer());
+    return file.text();
+  }
+
+  private async opfsWrite(path: string, data: string, encoding: 'utf8' | 'base64', append: boolean, recursive: boolean): Promise<{ uri: string }> {
+    const { parent, name } = await this.opfsResolveParent(path, recursive);
+    const handle = await parent.getFileHandle(name, { create: true });
+    const writable = await handle.createWritable({ keepExistingData: append });
+    if (append) writable.seek?.((await handle.getFile()).size);
+    const payload: BlobPart = encoding === 'base64' ? base64ToBuffer(data) : data;
+    await writable.write(payload);
+    await writable.close();
+    return { uri: `opfs:/${path}` };
+  }
+
+  private async opfsDelete(path: string): Promise<void> {
+    const { parent, name } = await this.opfsResolveParent(path, false);
+    await parent.removeEntry(name, { recursive: false }).catch(() => {}); // no-throw if absent
+  }
+
+  private async opfsList(path: string): Promise<Array<{ name: string; type: 'file' | 'dir' }>> {
+    let dir = await this.opfsRoot();
+    for (const seg of this.opfsSegments(path)) dir = await dir.getDirectoryHandle(seg);
+    const out: Array<{ name: string; type: 'file' | 'dir' }> = [];
+    for await (const [name, handle] of (dir as any).entries()) {
+      out.push({ name, type: handle.kind === 'directory' ? 'dir' : 'file' });
+    }
+    return out;
+  }
+
+  private async opfsMkdir(path: string): Promise<void> {
+    let dir = await this.opfsRoot();
+    for (const seg of this.opfsSegments(path)) dir = await dir.getDirectoryHandle(seg, { create: true });
+  }
+
+  private async opfsStat(path: string): Promise<{ name: string; type: 'file' | 'dir'; size?: number; mtime?: number }> {
+    const { parent, name } = await this.opfsResolveParent(path, false);
+    const fileHandle = await parent.getFileHandle(name).catch(() => null);
+    if (fileHandle) {
+      const f = await fileHandle.getFile();
+      return { name, type: 'file', size: f.size, mtime: f.lastModified };
+    }
+    await parent.getDirectoryHandle(name).catch(() => { throw new KitError('NATIVE_ERROR', `No such path: ${path}`); });
+    return { name, type: 'dir' };
+  }
+
+  /** Document picker via a hidden `<input type=file>` (works everywhere; reuses the photos pattern). */
+  private pickDocuments(types?: string[], multiple = false): Promise<Array<{ name: string; mimeType: string; size: number; base64: string }>> {
+    const toPicked = async (file: File) => ({
+      name: file.name,
+      mimeType: file.type || 'application/octet-stream',
+      size: file.size,
+      base64: bufferToBase64(await file.arrayBuffer()),
+    });
+    return new Promise((resolve) => {
+      const input = document.createElement('input');
+      input.type = 'file';
+      if (multiple) input.multiple = true;
+      if (types?.length) input.accept = types.join(',');
+      input.onchange = async () => {
+        const files = Array.from(input.files ?? []);
+        resolve(await Promise.all(files.map(toPicked)));
+      };
+      input.oncancel = () => resolve([]);
+      input.click();
+    });
+  }
+
   /** Minimal action sheet — fixed bottom panel, resolves option index or null on cancel. */
   private showActionSheet(title: string | undefined, options: string[], cancel: string): Promise<number | null> {
     return new Promise((resolve) => {

package/src/index.ts

@@ -23,6 +23,7 @@ export type { ImpactStyle, NotifyType } from './modules/haptics';
 export type { SharePayload, ShareFile } from './modules/share';
 export type { Orientation, OrientationLock } from './modules/screen';
 export type { KeyboardInfo } from './modules/keyboard';
+export type { FsDirectory, FsEncoding, FsEntry, PickedFile } from './modules/fs';
 export type { DeviceInfo } from './modules/device';
 export type { ScheduleOptions } from './modules/notifications';
 export type { PushMessage, PushPlatform, PushToken } from './modules/push';

package/src/modules/fs.ts

@@ -0,0 +1,109 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/** App-scoped storage roots — paths are resolved relative to one of these.
+ *  - `documents`: user-visible (iOS Documents — iCloud-backed-up · Android getExternalFilesDir —
+ *    NOT auto-backed-up, lives on shared/external storage).
+ *  - `data`: app-private (iOS Application Support — backed up · Android getFilesDir — included in
+ *    Auto Backup by default, subject to the app's backup rules). Default.
+ *  - `cache`: evictable, the OS may purge it and it isn't backed up (iOS Caches · Android getCacheDir). */
+export type FsDirectory = 'documents' | 'data' | 'cache';
+
+/** Text vs binary payload encoding. `utf8` reads/writes a string; `base64` a raw byte blob. */
+export type FsEncoding = 'utf8' | 'base64';
+
+/** One entry returned by {@link FsModule.list} / {@link FsModule.stat}. */
+export interface FsEntry {
+  /** Base name (list) or full relative path (stat input echo). */
+  name: string;
+  type: 'file' | 'dir';
+  /** Bytes for a file; omitted/0 for a dir. */
+  size?: number;
+  /** Last-modified epoch ms. */
+  mtime?: number;
+  /** Native URI (`file://` on native, omitted on web). */
+  uri?: string;
+}
+
+/** A document chosen via {@link FsModule.pickFile}. `base64` carries the bytes inline. */
+export interface PickedFile {
+  name: string;
+  mimeType: string;
+  size: number;
+  base64?: string;
+}
+
+export interface FsReadOptions { dir?: FsDirectory; encoding?: FsEncoding }
+export interface FsWriteOptions { dir?: FsDirectory; encoding?: FsEncoding; recursive?: boolean }
+export interface FsDirOptions { dir?: FsDirectory }
+export interface FsMkdirOptions { dir?: FsDirectory; recursive?: boolean }
+export interface FsPickOptions {
+  /** MIME types / extensions to allow (e.g. `['application/pdf', 'image/*']`). Omit = any. */
+  types?: string[];
+  /** Allow multi-select (default false). */
+  multiple?: boolean;
+}
+
+/**
+ * Native filesystem + document picker — ONE API across platforms.
+ *
+ * Read/write/list/stat files under three app-scoped roots ({@link FsDirectory}) plus a system
+ * document picker. No runtime permission is needed: every root lives inside the app sandbox and
+ * the picker hands back security-scoped (iOS) / SAF (Android) URIs the user explicitly chose.
+ *
+ * Native (iOS `FileManager`, Android `java.io.File`) → `capability === 'native'`. Web maps file
+ * I/O to the Origin Private File System (`'web'` where present, else `'none'`) and `pickFile` to
+ * the File System Access API / a hidden `<input type=file>` fallback. Branch on {@link capability}.
+ */
+export class FsModule {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' on a shell · 'web' where OPFS exists · else 'none'. */
+  get capability() {
+    return this.kit.capability('fs');
+  }
+
+  /** Read a file. `utf8` (default) → string; `base64` → base64 string. */
+  read(path: string, opts: FsReadOptions = {}): Promise<string> {
+    return this.kit.invoke('fs.read', { path, ...opts });
+  }
+
+  /** Write `data` to `path` (overwrites). `recursive` creates missing parent dirs. → `{ uri }`. */
+  write(path: string, data: string, opts: FsWriteOptions = {}): Promise<{ uri: string }> {
+    return this.kit.invoke('fs.write', { path, data, ...opts });
+  }
+
+  /** Append `data` to `path` (creates it if absent). */
+  append(path: string, data: string, opts: FsWriteOptions = {}): Promise<void> {
+    return this.kit.invoke('fs.append', { path, data, ...opts });
+  }
+
+  /** Delete a file or empty directory. No-throw if it doesn't exist. */
+  delete(path: string, opts: FsDirOptions = {}): Promise<void> {
+    return this.kit.invoke('fs.delete', { path, ...opts });
+  }
+
+  /** List a directory's immediate children. */
+  list(path: string, opts: FsDirOptions = {}): Promise<FsEntry[]> {
+    return this.kit.invoke('fs.list', { path, ...opts });
+  }
+
+  /** Create a directory. `recursive` (default true) makes intermediate dirs. */
+  mkdir(path: string, opts: FsMkdirOptions = {}): Promise<void> {
+    return this.kit.invoke('fs.mkdir', { path, ...opts });
+  }
+
+  /** Stat a file/dir → `{ name, type, size, mtime, uri }`. */
+  stat(path: string, opts: FsDirOptions = {}): Promise<FsEntry> {
+    return this.kit.invoke('fs.stat', { path, ...opts });
+  }
+
+  /** Resolve a path to a URI suitable for `kit.share` (`file://` native, content:// Android). */
+  getUri(path: string, opts: FsDirOptions = {}): Promise<string> {
+    return this.kit.invoke('fs.getUri', { path, ...opts });
+  }
+
+  /** Open the system document picker. Resolves with the chosen files (bytes inline as base64). */
+  pickFile(opts: FsPickOptions = {}): Promise<PickedFile[]> {
+    return this.kit.invoke('fs.pickFile', opts);
+  }
+}