@nebula-rn/client

@nebula-rn/client is the main API package for miniapp developers, providing a stable interface for calling host capabilities. All APIs communicate with the host through the Nebula protocol layer.

QR Code / Barcode Scanning

scanCode(options?)

Opens the host-managed scanning UI and returns the scan result. The interface automatically closes and returns data upon successful scan; throws an exception on failure.

function scanCode(options?: ScanCodeOptions): Promise<ScanCodeData>;

Parameters ScanCodeOptions:

Return value ScanCodeData:

Timeout: 120000ms

Error codes:

scanCodeSafe(options?)

Same functionality as scanCode, but does not throw exceptions. Returns a Result type instead, suitable for scenarios where you want to handle both success and failure uniformly at the call site.

function scanCodeSafe(options?: ScanCodeOptions): Promise<ScanCodeResult>;

Return value ScanCodeResult:

// Success
{ ok: true, data: ScanCodeData }

// Failure
{ ok: false, error: { code: ScanCodeErrorCode, message: string } }

Media

chooseMedia(options?)

Selects images/videos from the album or camera.

function chooseMedia(options?: ChooseMediaOption): Promise<ChooseMediaResult>;

Parameters ChooseMediaOption:

Return value ChooseMediaResult:

ChooseMediaFile structure:

Timeout: 120000ms

previewImages(options)

Opens a full-screen image preview interface, supporting browsing multiple images and saving.

function previewImages(options: PreviewImageOptions): Promise<void>;

Parameters PreviewImageOptions:

Timeout: 120000ms

getImageInfo(option)

Gets image dimensions, type, and other information.

function getImageInfo(
  option: GetImageInfoOption,
): Promise<GetImageInfoSuccessResult>;

Parameters GetImageInfoOption:

Return value GetImageInfoSuccessResult:

compressImage(options)

Compresses and scales an image, outputting in JPEG format.

function compressImage(options: CompressImageOption): Promise<string>;

Parameters CompressImageOption:

Return value: Promise<string> — Path to the compressed image.

saveMedia(url, type, options?)

Saves an image or video to the system photo album.

function saveMedia(
  url: string,
  type: MediaType,
  options?: SaveMediaOptions,
): Promise<string>;

Parameters:

Return value: Promise<string> — System resource URI after saving.

Location

getLocation(options?)

Gets the current device geographic location.

function getLocation(options?: GetLocationOption): Promise<GetLocationResult>;

Parameters GetLocationOption:

Return value GetLocationResult:

onLocationChange(enableHighAccuracy, onSuccess, onError?)

Subscribes to location change events, continuously receiving location updates.

function onLocationChange(
  enableHighAccuracy: boolean,
  onSuccess: (data: LocationData) => void,
  onError?: (error: unknown) => void,
): () => void;

Parameters:

Callback parameter LocationData:

Return value: () => void — Call this function to unsubscribe.

Storage

setStorage(options)

Writes data to local key-value storage. Values are serialized to JSON strings. Uses the MMKV storage engine under the hood.

function setStorage(options: SetStorageOption): Promise<void>;

Parameters SetStorageOption:

getStorage<T>(key)

Reads data from local storage. Values are deserialized from JSON strings to their original types.

function getStorage<T>(key: string): Promise<T>;

Parameters:

Return value: Promise<T> — Deserialized data.

Exception: Throws an Error if the key does not exist, with message 'getStorage:fail data not found'.

getStorageInfo()

Gets storage usage information.

function getStorageInfo(): Promise<GetStorageInfoResult>;

Return value GetStorageInfoResult:

Device

getSystemInfo()

Gets system information including device hardware, screen dimensions, and safe areas.

function getSystemInfo(): Promise<SystemInfo>;

Return value SystemInfo:

SafeArea structure:

getAppBaseInfo()

Gets basic information about the host application.

function getAppBaseInfo(): Promise<AppBaseInfo>;

Return value AppBaseInfo:

getScreenBrightness()

Gets the current screen brightness.

function getScreenBrightness(): Promise<number>;

Return value: Promise<number> — Brightness value ranging from 0 (darkest) to 1 (brightest).

makePhoneCall(phoneNumber)

Brings up the system dialer interface.

function makePhoneCall(phoneNumber: string): Promise<boolean>;

Parameters:

Return value: Promise<boolean> — Whether the dialer was successfully invoked.

Clipboard

getClipboardData()

Reads text content from the system clipboard.

function getClipboardData(): Promise<string>;

Return value: Promise<string> — Text content from the clipboard.

setClipboardData(data)

Writes text to the system clipboard.

function setClipboardData(data: string): Promise<void>;

Parameters:

File Transfer

downloadFile(options)

Downloads a file to a local temporary path. Returns a Task object that supports aborting the download and listening for progress.

function downloadFile(options: DownloadFileOption): DownloadTask;

Parameters DownloadFileOption:

Return value DownloadTask:

DownloadTask is both a Promise and a Task object. You can await it for the result, or call methods to control the download.

Progress callback parameters DownloadProgressRes:

Final return value DownloadFileResult:

uploadFile(options)

Uploads a local file to a server. Returns a Task object that supports aborting the upload and listening for progress.

function uploadFile(options: UploadFileOption): UploadTask;

Parameters UploadFileOption:

Return value UploadTask:

Same structure as DownloadTask, supporting abort(), onProgressUpdate(), onHeadersReceived(), etc.

Progress callback parameters UploadProgressRes:

Final return value UploadFileResult:

removeFile(options)

Deletes a file from the sandbox.

function removeFile(options: { filePath: string }): Promise<void>;

Parameters:

Exception: Throws a FILE_NOT_FOUND error if the file does not exist.

File System

getFileSystemManager()

Gets the file system manager singleton, providing complete sandbox file operations. All file paths are automatically resolved relative to the miniapp sandbox directory.

function getFileSystemManager(): FileSystemManager;

FileSystemManager.access(options)

Checks whether a file or directory exists. Resolves if it exists, rejects with a FILE_NOT_FOUND error if it does not.

access(options: { path: string }): Promise<void>

FileSystemManager.readFile(options)

Reads file content.

readFile(options: FileReadOption): Promise<{ data: string }>

FileSystemManager.writeFile(options)

Writes to a file. If the file already exists, it will be overwritten.

writeFile(options: FileWriteOption): Promise<void>

FileSystemManager.appendFile(options)

Appends content to the end of a file.

appendFile(options: { filePath: string; data: string; encoding?: string }): Promise<void>

FileSystemManager.copyFile(options)

Copies a file.

copyFile(options: { srcPath: string; destPath: string }): Promise<void>

FileSystemManager.rename(options)

Renames or moves a file/directory.

rename(options: { oldPath: string; newPath: string }): Promise<void>

FileSystemManager.unlink(options)

Deletes a file.

unlink(options: { filePath: string }): Promise<void>

FileSystemManager.mkdir(options)

Creates a directory.

mkdir(options: { dirPath: string; recursive?: boolean }): Promise<void>

FileSystemManager.rmdir(options)

Deletes a directory.

rmdir(options: { dirPath: string; recursive?: boolean }): Promise<void>

FileSystemManager.readdir(options)

Lists files and subdirectories in a directory.

readdir(options: { dirPath: string }): Promise<{ files: string[] }>

FileSystemManager.saveFile(options)

Saves a temporary file to the sandbox. If filePath is not specified, automatically generates a name using a timestamp.

saveFile(options: { tempFilePath: string; filePath?: string }): Promise<{ savedFilePath: string }>

FileSystemManager.getFileInfo(options)

Gets file size and hash digest.

getFileInfo(options: GetFileInfoOption): Promise<GetFileInfoResult>

Return value GetFileInfoResult:

Network

getNetworkType()

Gets the current network connection type.

function getNetworkType(): Promise<string>;

Return value: Promise<string> — Network type, such as 'wifi', 'cellular', 'none', or 'unknown'.

onNetworkStatusChange(callback)

Subscribes to network status change events.

function onNetworkStatusChange(
  callback: (res: NetworkStatusChangeResult) => void,
): () => void;

Parameters:

Callback parameter NetworkStatusChangeResult:

Return value: () => void — Call this function to unsubscribe.

Sensors

All sensor APIs return an unsubscribe function. After subscription, they continuously receive data updates until the unsubscribe function is called.

onAccelerometerChange(callback, interval?)

Subscribes to accelerometer data changes.

function onAccelerometerChange(
  callback: (data: SensorData) => void,
  interval?: number,
): () => void;

Parameters:

Callback parameter SensorData:

Return value: () => void — Call this function to unsubscribe.

onGyroscopeChange(callback, interval?)

Subscribes to gyroscope data changes. Parameter and return value structure is the same as onAccelerometerChange.

function onGyroscopeChange(
  callback: (data: SensorData) => void,
  interval?: number,
): () => void;

onMagnetometerChange(callback, interval?)

Subscribes to magnetometer data changes. Parameter and return value structure is the same as onAccelerometerChange.

function onMagnetometerChange(
  callback: (data: SensorData) => void,
  interval?: number,
): () => void;

onBarometerChange(callback)

Subscribes to barometer data changes.

function onBarometerChange(callback: (data: BarometerData) => void): () => void;

Parameters:

Callback parameter BarometerData:

Return value: () => void — Call this function to unsubscribe.

Screenshot Listener

onUserCaptureScreen(callback)

Listens for user screenshot events.

function onUserCaptureScreen(callback: () => void): () => void;

Parameters:

Return value: () => void — Call this function to stop listening.

Miniapp Update

getMiniAppUpdateInfo()

Checks whether an update is available for the current miniapp. Does not require any parameters; automatically uses the appId of the currently running miniapp.

function getMiniAppUpdateInfo(): Promise<MiniAppUpdateInfo>;

Return value MiniAppUpdateInfo:

Timeout: 15000ms

applyMiniAppUpdate()

Downloads and installs the latest version of the bundle. Typically called after confirming an update via getMiniAppUpdateInfo().

function applyMiniAppUpdate(): Promise<MiniAppUpdateInfo>;

Return value: Same MiniAppUpdateInfo object as getMiniAppUpdateInfo, reflecting the state after the update.

Timeout: 120000ms

Common Conventions

Timeouts

File Paths

• All file paths are automatically resolved relative to the miniapp sandbox directory
• /Documents/ paths are mapped to DocumentDirectoryPath
• The file:// protocol prefix is automatically stripped
• Miniapp path prefix is /Documents/MiniApps/{appId}

Subscription Pattern

All subscription APIs (sensors, network, location, screenshot) follow a unified pattern:

// Subscribe
const unsubscribe = onXxxChange(callback);

// Unsubscribe
unsubscribe();