@nebula-rn/client 0.0.1

package/dist/uploadFile/index.js

@@ -0,0 +1,6 @@
+import { createHostTask } from '../runtime/host';
+export const uploadFile = (options) => {
+    return createHostTask('uploadFile', options, {
+        timeoutMs: options.timeout ?? 60000,
+    });
+};

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@nebula-rn/client",
+  "version": "0.0.1",
+  "description": "Nebula miniapp client API surface",
+  "author": "Hector Zhuang",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "types": "types/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "types",
+    "apiList.js",
+    "libList.js"
+  ],
+  "scripts": {
+    "prod": "npm run build",
+    "assets": "cpy 'src/**/*.png' '!src/__tests__/*' dist",
+    "prebuild": "npm run clean",
+    "clean": "rimraf ./dist apiList.js libList.js",
+    "build": "tsc && npm run assets",
+    "dev": "npm run assets && tsc --watch",
+    "prepack": "npm run build",
+    "docs": "node ./script",
+    "lint": "eslint src --ext .js,.jsx.ts,.tsx",
+    "test": "jest --silent",
+    "test:ci": "jest --ci -i --coverage --silent",
+    "test:coverage": "jest --coverage",
+    "test:dev": "jest --watch",
+    "script": "node ./script"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hector-Zhuang/nebula.git",
+    "directory": "packages/api"
+  },
+  "bugs": {
+    "url": "https://github.com/Hector-Zhuang/nebula/issues"
+  },
+  "homepage": "https://github.com/Hector-Zhuang/nebula/tree/main/packages/api#readme",
+  "keywords": ["nebula", "superapp", "miniapp", "react-native", "client"],
+  "publishConfig": { "access": "public" },
+  "engines": {
+    "node": ">= 18"
+  },
+  "dependencies": {
+    "@nebula-rn/sdk": "^0.0.1",
+    "@dr.pogodin/react-native-fs": "^2.37.0",
+    "base64-js": "^1.5.1",
+    "prop-types": "^15.8.1",
+    "react-native-image-picker": "^8.2.1",
+    "react-native-screenshot-aware": "^2.0.0",
+    "react-native-sensors": "^7.3.6"
+  },
+  "devDependencies": {
+    "@bam.tech/react-native-image-resizer": "^3.0.11",
+    "cpy-cli": "^5.0.0",
+    "dpdm": "^3.14.0",
+    "react-native-image-zoom-viewer": "^3.0.1",
+    "react-native-root-siblings": "^5.0.1",
+    "react-native-safe-area-context": "^5.7.0"
+  },
+  "peerDependencies": {
+    "@bam.tech/react-native-image-resizer": "^3.0.11",
+    "@react-native-camera-roll/camera-roll": "^7.10.2",
+    "@react-native-community/geolocation": "^3.4.0",
+    "@react-native-community/netinfo": "^12.0.1",
+    "react": ">=19",
+    "react-native": ">=0.83",
+    "react-native-device-info": "^15.0.2",
+    "react-native-image-zoom-viewer": "^3.0.1",
+    "react-native-mmkv": "^4.2.0",
+    "react-native-safe-area-context": "^5.7.0"
+  }
+}

package/src/chooseMedia/index.ts

@@ -0,0 +1,36 @@
+import { invokeHostApi } from '../runtime/host';
+
+export interface ChooseMediaFile {
+  tempFilePath: string;
+  size: number;
+  duration?: number;
+  height?: number;
+  width?: number;
+  thumbTempFilePath?: string;
+  fileType: 'image' | 'video';
+}
+
+export interface ChooseMediaResult {
+  tempFiles: ChooseMediaFile[];
+  type: 'image' | 'video' | 'mix';
+}
+
+export interface ChooseMediaOption {
+  count?: number;
+  mediaType?: ('image' | 'video' | 'mix')[];
+  sourceType?: ('album' | 'camera')[];
+  maxDuration?: number;
+  sizeType?: ('original' | 'compressed')[];
+  camera?: 'back' | 'front';
+}
+
+export const chooseMedia = (
+  options: ChooseMediaOption = {},
+): Promise<ChooseMediaResult> => {
+  return invokeHostApi<ChooseMediaResult>(
+    'chooseMedia',
+    options,
+    '1.0',
+    120000,
+  );
+};

package/src/compressImage/index.ts

@@ -0,0 +1,14 @@
+import { invokeHostApi } from '../runtime/host';
+
+export interface CompressImageOption {
+  src: string;
+  quality?: number;
+  compressedWidth?: number;
+  compressedHeight?: number;
+}
+
+export const compressImage = (
+  options: CompressImageOption,
+): Promise<string> => {
+  return invokeHostApi<string>('compressImage', options);
+};

package/src/descriptions.ts

@@ -0,0 +1,294 @@
+import { Miniapp } from '@nebula-rn/sdk';
+import type {
+  NebulaHostApiDescription,
+  NebulaHostApiDescriptionMap,
+} from '@nebula-rn/sdk';
+
+export type NebulaPublicApiDescription = NebulaHostApiDescription & {
+  kind?: 'api' | 'manager' | 'subscription' | 'task' | 'utility';
+  methods?: Record<string, NebulaHostApiDescription>;
+};
+
+export type NebulaPublicApiDescriptionMap = Record<
+  string,
+  NebulaPublicApiDescription
+>;
+
+export const nebulaApiDescriptions: NebulaPublicApiDescriptionMap = {
+  chooseMedia: {
+    summary:
+      'Open the host media picker and return selected image or video assets.',
+    kind: 'api',
+    tags: ['media', 'picker'],
+  },
+  compressImage: {
+    summary: 'Resize and compress an image through the host runtime.',
+    kind: 'api',
+    tags: ['media', 'image'],
+  },
+  downloadFile: {
+    summary:
+      'Start a host-managed download task with progress and abort support.',
+    kind: 'task',
+    tags: ['file', 'network'],
+  },
+  uploadFile: {
+    summary:
+      'Start a host-managed upload task with progress and abort support.',
+    kind: 'task',
+    tags: ['file', 'network'],
+  },
+  getAppBaseInfo: {
+    summary:
+      'Return basic host app information for the current miniapp runtime.',
+    kind: 'api',
+    tags: ['device', 'app'],
+  },
+  getClipboardData: {
+    summary: 'Read plain text from the system clipboard.',
+    kind: 'api',
+    tags: ['clipboard'],
+  },
+  getFileInfo: {
+    summary: 'Read size and digest information for a file path.',
+    kind: 'api',
+    tags: ['file'],
+  },
+  getFileSystemManager: {
+    summary: 'Return a file system manager bound to host-backed file APIs.',
+    kind: 'manager',
+    tags: ['file'],
+    methods: {
+      access: {
+        summary: 'Check whether a path exists and is accessible.',
+        tags: ['file'],
+      },
+      appendFile: {
+        summary: 'Append text data to a file path.',
+        tags: ['file'],
+      },
+      saveFile: {
+        summary: 'Persist a temp file into the miniapp sandbox.',
+        tags: ['file'],
+      },
+      copyFile: {
+        summary: 'Copy a file from one path to another.',
+        tags: ['file'],
+      },
+      mkdir: {
+        summary: 'Create a directory path recursively.',
+        tags: ['file'],
+      },
+      readFile: {
+        summary: 'Read a file as text with optional encoding.',
+        tags: ['file'],
+      },
+      readdir: {
+        summary: 'List child entries in a directory.',
+        tags: ['file'],
+      },
+      rename: {
+        summary: 'Rename or move a file or directory.',
+        tags: ['file'],
+      },
+      rmdir: {
+        summary: 'Remove a directory path recursively.',
+        tags: ['file'],
+      },
+      unlink: {
+        summary: 'Delete a file path.',
+        tags: ['file'],
+      },
+      writeFile: {
+        summary: 'Write text data to a file path.',
+        tags: ['file'],
+      },
+      getFileInfo: {
+        summary: 'Read file stat information for a sandbox path.',
+        tags: ['file'],
+      },
+    },
+  },
+  getImageInfo: {
+    summary:
+      'Read width, height, and metadata information for an image source.',
+    kind: 'api',
+    tags: ['media', 'image'],
+  },
+  getLocation: {
+    summary: 'Get the current device location once.',
+    description:
+      'The host may request runtime location permission before resolving.',
+    kind: 'api',
+    tags: ['location'],
+  },
+  getScreenBrightness: {
+    summary: 'Read the current screen brightness reported by the device.',
+    kind: 'api',
+    tags: ['device'],
+  },
+  getStorage: {
+    summary:
+      'Read a JSON-serializable value from host-backed key-value storage.',
+    kind: 'api',
+    tags: ['storage'],
+  },
+  getStorageInfo: {
+    summary: 'Read host-backed storage usage and key information.',
+    kind: 'api',
+    tags: ['storage'],
+  },
+  getSystemInfo: {
+    summary:
+      'Return device, screen, and safe-area information for layout and diagnostics.',
+    kind: 'api',
+    tags: ['device', 'layout'],
+  },
+  onLocationChange: {
+    summary: 'Subscribe to host location change events.',
+    kind: 'subscription',
+    tags: ['location', 'subscription'],
+  },
+  makePhoneCall: {
+    summary: 'Open the system dialer for a phone number.',
+    kind: 'api',
+    tags: ['device', 'communication'],
+  },
+  getMiniAppUpdateInfo: {
+    summary:
+      'Read the installed miniapp version, update strategy, and whether a newer remote version exists.',
+    kind: 'api',
+    tags: ['miniapp', 'update'],
+  },
+  applyMiniAppUpdate: {
+    summary:
+      'Install the newest available bundle for the current miniapp and return the updated version state.',
+    kind: 'api',
+    tags: ['miniapp', 'update'],
+  },
+  saveMedia: {
+    summary: 'Save a photo or video into the system media library.',
+    kind: 'api',
+    tags: ['media'],
+  },
+  getNetworkType: {
+    summary: 'Read the current network connection type and connectivity state.',
+    kind: 'api',
+    tags: ['network'],
+  },
+  onNetworkStatusChange: {
+    summary: 'Subscribe to host network status change events.',
+    kind: 'subscription',
+    tags: ['network', 'subscription'],
+  },
+  onUserCaptureScreen: {
+    summary: 'Subscribe to host screenshot capture events.',
+    kind: 'subscription',
+    tags: ['device', 'subscription'],
+  },
+  previewImage: {
+    summary:
+      'Open a host-managed fullscreen image preview modal for one or more image URLs.',
+    kind: 'api',
+    tags: ['media', 'image', 'modal'],
+  },
+  scanCode: {
+    summary:
+      'Open a host-managed scanner modal and return the first detected barcode or QR code.',
+    kind: 'api',
+    tags: ['camera', 'scanner', 'modal'],
+  },
+  scanCodeSafe: {
+    summary:
+      'Open the host scanner modal and always resolve with an ok/error result object.',
+    kind: 'api',
+    tags: ['camera', 'scanner', 'modal'],
+  },
+  onAccelerometerChange: {
+    summary: 'Subscribe to host accelerometer events.',
+    kind: 'subscription',
+    tags: ['sensor', 'subscription'],
+  },
+  onGyroscopeChange: {
+    summary: 'Subscribe to host gyroscope events.',
+    kind: 'subscription',
+    tags: ['sensor', 'subscription'],
+  },
+  onMagnetometerChange: {
+    summary: 'Subscribe to host magnetometer events.',
+    kind: 'subscription',
+    tags: ['sensor', 'subscription'],
+  },
+  onBarometerChange: {
+    summary: 'Subscribe to host barometer events.',
+    kind: 'subscription',
+    tags: ['sensor', 'subscription'],
+  },
+  setClipboardData: {
+    summary: 'Write plain text to the system clipboard.',
+    kind: 'api',
+    tags: ['clipboard'],
+  },
+  setStorage: {
+    summary:
+      'Persist a JSON-serializable value in host-backed key-value storage.',
+    kind: 'api',
+    tags: ['storage'],
+  },
+  storage: {
+    summary:
+      'Low-level storage helpers for host-backed key-value access and serialization.',
+    kind: 'utility',
+    tags: ['storage'],
+    methods: {
+      serializeStorageValue: {
+        summary:
+          'Serialize a JSON-serializable value before writing to storage.',
+        tags: ['storage'],
+      },
+      deserializeStorageValue: {
+        summary: 'Deserialize a stored JSON string into a typed value.',
+        tags: ['storage'],
+      },
+      setStorageItem: {
+        summary: 'Persist a raw storage item by key.',
+        tags: ['storage'],
+      },
+      getStorageItem: {
+        summary: 'Read a raw storage item by key.',
+        tags: ['storage'],
+      },
+      removeStorageItem: {
+        summary: 'Remove a raw storage item by key.',
+        tags: ['storage'],
+      },
+      clearStorageItems: {
+        summary: 'Clear all host-backed storage entries.',
+        tags: ['storage'],
+      },
+      getStorageKeys: {
+        summary: 'List all keys in host-backed storage.',
+        tags: ['storage'],
+      },
+      getStorageCurrentSize: {
+        summary: 'Return the approximate storage size in KB.',
+        tags: ['storage'],
+      },
+    },
+  },
+  removeFile: {
+    summary: 'Remove a file from the miniapp sandbox.',
+    kind: 'api',
+    tags: ['file'],
+  },
+};
+
+export function getNebulaApiDescriptions(): NebulaPublicApiDescriptionMap {
+  return nebulaApiDescriptions;
+}
+
+export function getHostApiDescriptions(
+  timeoutMs: number = 15000,
+): Promise<NebulaHostApiDescriptionMap> {
+  return Miniapp.getHostApiDescriptions(timeoutMs);
+}

package/src/file.ts

@@ -0,0 +1,89 @@
+import { createHostTask, invokeHostApi } from './runtime/host';
+
+export interface HeadersRes {
+  header: Record<string, string>;
+}
+
+export interface Task<T, P> {
+  abort(): Promise<void>;
+  onProgressUpdate(listener: (res: P) => void): void;
+  offProgressUpdate(listener: (res: P) => void): void;
+  onHeadersReceived(listener: (res: HeadersRes) => void): void;
+  offHeadersReceived(listener: (res: HeadersRes) => void): void;
+  then<TResult1 = T, TResult2 = never>(
+    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResult1 | TResult2>;
+  catch<TResult = never>(
+    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+  ): Promise<T | TResult>;
+}
+
+export interface DownloadProgressRes {
+  progress: number;
+  totalBytesWritten: number;
+  totalBytesExpectedToWrite: number;
+}
+
+export interface DownloadFileResult {
+  tempFilePath: string;
+  statusCode: number;
+}
+
+export interface DownloadFileOption {
+  url: string;
+  header?: Record<string, string>;
+  timeout?: number;
+  filePath?: string;
+}
+
+export type DownloadTask = Task<DownloadFileResult, DownloadProgressRes>;
+
+export const downloadFile = (options: DownloadFileOption): DownloadTask => {
+  return createHostTask<DownloadFileResult, DownloadProgressRes, HeadersRes>(
+    'downloadFile',
+    options,
+    {
+      timeoutMs: 60000,
+    },
+  );
+};
+
+export interface UploadProgressRes {
+  progress: number;
+  totalBytesSent: number;
+  totalBytesExpectedToSend: number;
+}
+
+export interface UploadFileResult {
+  data: string;
+  statusCode: number;
+}
+
+export interface UploadFileOption {
+  url: string;
+  filePath: string;
+  name: string;
+  header?: Record<string, string>;
+  formData?: Record<string, string>;
+}
+
+export type UploadTask = Task<UploadFileResult, UploadProgressRes>;
+
+export const uploadFile = (options: UploadFileOption): UploadTask => {
+  return createHostTask<UploadFileResult, UploadProgressRes, HeadersRes>(
+    'uploadFile',
+    options,
+    {
+      timeoutMs: 60000,
+    },
+  );
+};
+
+export interface RemoveFileOption {
+  filePath: string;
+}
+
+export const removeFile = (options: RemoveFileOption): Promise<void> => {
+  return invokeHostApi<void>('removeFile', options);
+};

package/src/getAppBaseInfo/index.ts

@@ -0,0 +1,10 @@
+import { invokeHostApi } from '../runtime/host';
+
+export function getAppBaseInfo() {
+  return invokeHostApi<{
+    version: string;
+    language: string;
+    enableDebug: boolean;
+    theme: string;
+  }>('getAppBaseInfo');
+}

package/src/getClipboardData/index.ts

@@ -0,0 +1,5 @@
+import { invokeHostApi } from '../runtime/host';
+
+export function getClipboardData() {
+  return invokeHostApi<string>('getClipboardData');
+}

package/src/getFileInfo/index.ts

@@ -0,0 +1,17 @@
+import { invokeHostApi } from '../runtime/host';
+
+export interface GetFileInfoOption {
+  filePath: string;
+  digestAlgorithm?: 'md5' | 'sha1' | 'sha256';
+}
+
+export interface GetFileInfoResult {
+  size: number;
+  digest: string;
+}
+
+export const getFileInfo = (
+  options: GetFileInfoOption,
+): Promise<GetFileInfoResult> => {
+  return invokeHostApi<GetFileInfoResult>('getFileInfo', options);
+};

package/src/getFileSystemManager/index.ts

@@ -0,0 +1,141 @@
+import { invokeHostApi } from '../runtime/host';
+import { GetFileInfoOption, GetFileInfoResult } from '../getFileInfo';
+
+export interface FileAccessOption {
+  path: string;
+}
+
+export interface FileAppendOption {
+  filePath: string;
+  data: string;
+  encoding?: 'ascii' | 'base64' | 'utf8';
+}
+
+export interface FileSaveOption {
+  tempFilePath: string;
+  filePath?: string;
+}
+
+export interface FileSaveResult {
+  savedFilePath: string;
+}
+
+export interface FileCopyOption {
+  srcPath: string;
+  destPath: string;
+}
+
+export interface FileMkdirOption {
+  dirPath: string;
+  recursive?: boolean;
+}
+
+export interface FileReadOption {
+  filePath: string;
+  encoding?: 'ascii' | 'base64' | 'utf8';
+  position?: number;
+  length?: number;
+}
+
+export interface FileReadResult {
+  data: string;
+}
+
+export interface FileReaddirOption {
+  dirPath: string;
+}
+
+export interface FileReaddirResult {
+  files: string[];
+}
+
+export interface FileRenameOption {
+  oldPath: string;
+  newPath: string;
+}
+
+export interface FileRmdirOption {
+  dirPath: string;
+  recursive?: boolean;
+}
+
+export interface FileUnlinkOption {
+  filePath: string;
+}
+
+export interface FileWriteOption {
+  filePath: string;
+  data: string;
+  encoding?: 'ascii' | 'base64' | 'utf8';
+}
+
+export interface FileSystemManager {
+  access(options: FileAccessOption): Promise<void>;
+  appendFile(options: FileAppendOption): Promise<void>;
+  saveFile(options: FileSaveOption): Promise<FileSaveResult>;
+  copyFile(options: FileCopyOption): Promise<void>;
+  mkdir(options: FileMkdirOption): Promise<void>;
+  readFile(options: FileReadOption): Promise<FileReadResult>;
+  readdir(options: FileReaddirOption): Promise<FileReaddirResult>;
+  rename(options: FileRenameOption): Promise<void>;
+  rmdir(options: FileRmdirOption): Promise<void>;
+  unlink(options: FileUnlinkOption): Promise<void>;
+  writeFile(options: FileWriteOption): Promise<void>;
+  getFileInfo(options: GetFileInfoOption): Promise<GetFileInfoResult>;
+}
+
+class FileSystemManagerImpl implements FileSystemManager {
+  public access(options: FileAccessOption): Promise<void> {
+    return invokeHostApi<void>('fileSystem.access', options);
+  }
+
+  public appendFile(options: FileAppendOption): Promise<void> {
+    return invokeHostApi<void>('fileSystem.appendFile', options);
+  }
+
+  public saveFile(options: FileSaveOption): Promise<FileSaveResult> {
+    return invokeHostApi<FileSaveResult>('fileSystem.saveFile', options);
+  }
+
+  public copyFile(options: FileCopyOption): Promise<void> {
+    return invokeHostApi<void>('fileSystem.copyFile', options);
+  }
+
+  public mkdir(options: FileMkdirOption): Promise<void> {
+    return invokeHostApi<void>('fileSystem.mkdir', options);
+  }
+
+  public readFile(options: FileReadOption): Promise<FileReadResult> {
+    return invokeHostApi<FileReadResult>('fileSystem.readFile', options);
+  }
+
+  public readdir(options: FileReaddirOption): Promise<FileReaddirResult> {
+    return invokeHostApi<FileReaddirResult>('fileSystem.readdir', options);
+  }
+
+  public rename(options: FileRenameOption): Promise<void> {
+    return invokeHostApi<void>('fileSystem.rename', options);
+  }
+
+  public rmdir(options: FileRmdirOption): Promise<void> {
+    return invokeHostApi<void>('fileSystem.rmdir', options);
+  }
+
+  public unlink(options: FileUnlinkOption): Promise<void> {
+    return invokeHostApi<void>('fileSystem.unlink', options);
+  }
+
+  public writeFile(options: FileWriteOption): Promise<void> {
+    return invokeHostApi<void>('fileSystem.writeFile', options);
+  }
+
+  public getFileInfo(options: GetFileInfoOption): Promise<GetFileInfoResult> {
+    return invokeHostApi<GetFileInfoResult>('fileSystem.getFileInfo', options);
+  }
+}
+
+const fileSystemManager = new FileSystemManagerImpl();
+
+export const getFileSystemManager = (): FileSystemManager => {
+  return fileSystemManager;
+};