@nebula-rn/host-apis

@nebula-rn/host-apis provides official host API feature implementations. Host apps can directly use these pre-built features and register them with the runtime via NebulaAPI.wrap().

Version: 0.0.1

Quick Start

Register All Default APIs

import { NebulaAPI } from '@nebula-rn/sdk';
import { defaultHostApis } from '@nebula-rn/host-apis';

export default NebulaAPI.wrap({
  serverBaseURL: 'https://api.example.com',
  hostApis: defaultHostApis,
})(App);

Register on Demand

import { scanCodeHostApi, previewImageHostApi } from '@nebula-rn/host-apis';

NebulaAPI.wrap({
  hostApis: [scanCodeHostApi, previewImageHostApi],
})(App);

Exports

defaultHostApis = [scanCodeHostApi, previewImageHostApi, ...coreHostApis]

Modal APIs

scanCode

Opens the host-managed scanning UI, supporting QR codes and barcodes.

API Name: scanCode

Version: 1.0

Payload:

Return Value:

Permission Required: Camera permission.

Platform Differences:

Error Codes:

previewImage

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

API Name: previewImage

Version: 1.0

Payload:

Return Value: Same as Payload structure.

Permission Required: None.

Device and App

getAppBaseInfo

Gets basic information about the host application.

API Name: getAppBaseInfo

Payload: {} (no parameters)

Return Value:

getSystemInfo

Gets device, screen, and safe area information.

API Name: getSystemInfo

Payload: {} (no parameters)

Return Value:

SafeArea Fields:

Platform Differences:

getScreenBrightness

Gets the current screen brightness.

API Name: getScreenBrightness

Payload: {} (no parameters)

Return Value: number (brightness value 0-1).

makePhoneCall

Opens the system dialer with the specified number.

API Name: makePhoneCall

Payload:

Return Value: boolean (true if dialer was successfully invoked, false if number is empty or failed).

Clipboard

getClipboardData

Reads text content from the clipboard.

API Name: getClipboardData

Payload: {} (no parameters)

Return Value: string (clipboard text).

setClipboardData

Writes text to the clipboard.

API Name: setClipboardData

Payload:

Return Value: null

Location

getLocation

Gets the current device location (one-time).

API Name: getLocation

Payload:

Return Value:

Permission Required (Android): ACCESS_FINE_LOCATION, falls back to ACCESS_COARSE_LOCATION.

Error Codes:

locationChange.subscribe

Starts continuously listening for location changes.

API Name: locationChange.subscribe

Payload:

Return Value:

Subscription Event Data:

Timeout: 10000ms.

distanceFilter: 0 (any movement triggers callback).

locationChange.unsubscribe

Stops listening for location changes.

API Name: locationChange.unsubscribe

Payload:

Return Value: null

Media

chooseMedia

Opens the media picker to get images/videos from the album or camera.

API Name: chooseMedia

Timeout: 120000ms

Payload:

Return Value:

TempFile Fields:

Compression Quality: compressed = 0.8, original = 1.0.

Error Codes:

getImageInfo

Gets image dimension information.

API Name: getImageInfo

Payload:

Return Value:

compressImage

Compresses an image, outputting in JPEG format.

API Name: compressImage

Payload:

Return Value: string (compressed image URI).

saveMedia

Saves an image or video to the system photo album.

API Name: saveMedia

Payload:

Return Value: string (URI/path in system photo album).

Implementation: Uses CameraRoll to save to system media library.

Storage

Based on MMKV (Memory Mapped KV Store), ID: nebula.host.api.storage.

storage.setItem

Writes a key-value pair.

API Name: storage.setItem

Payload:

Return Value: null

storage.getItem

Reads a key-value pair.

API Name: storage.getItem

Payload:

Return Value:

storage.removeItem

Deletes a key-value pair.

API Name: storage.removeItem

Payload:

Return Value: null

storage.clearItems

Clears all stored data and releases memory.

API Name: storage.clearItems

Payload: {} (no parameters)

Return Value: null

storage.getKeys

Gets all stored key names.

API Name: storage.getKeys

Payload: {} (no parameters)

Return Value:

storage.getCurrentSize

Gets the current storage size.

API Name: storage.getCurrentSize

Payload: {} (no parameters)

Return Value:

File System

fileSystem.access

Checks whether a file or directory exists.

API Name: fileSystem.access

Payload:

Return Value: null

Error Codes:

fileSystem.readFile

Reads file content.

API Name: fileSystem.readFile

Payload:

Return Value:

fileSystem.writeFile

Writes to a file.

API Name: fileSystem.writeFile

Payload:

Return Value: null

fileSystem.appendFile

Appends content to the end of a file.

API Name: fileSystem.appendFile

Payload:

Return Value: null

fileSystem.copyFile

Copies a file.

API Name: fileSystem.copyFile

Payload:

Return Value: null

fileSystem.rename

Renames or moves a file/directory.

API Name: fileSystem.rename

Payload:

Return Value: null

fileSystem.unlink

Deletes a file.

API Name: fileSystem.unlink

Payload:

Return Value: null

fileSystem.mkdir

Creates a directory (recursively).

API Name: fileSystem.mkdir

Payload:

Return Value: null

fileSystem.rmdir

Deletes a directory (recursively).

API Name: fileSystem.rmdir

Payload:

Return Value: null

fileSystem.readdir

Lists directory contents.

API Name: fileSystem.readdir

Payload:

Return Value:

fileSystem.saveFile

Saves a temporary file to the miniapp sandbox.

API Name: fileSystem.saveFile

Payload:

Return Value:

fileSystem.getFileInfo

Gets file information and digest.

API Name: fileSystem.getFileInfo

Payload:

Return Value:

removeFile

Deletes a sandbox file.

API Name: removeFile

Payload:

Return Value: null

Error Codes:

Path Resolution Rules

• Paths starting with file:// are normalized.
• Miniapp paths are resolved relative to /Documents/MiniApps/{appId}/.
• Paths starting with /Documents/ are resolved to ${RNFS.DocumentDirectoryPath}.

Network

getNetworkType

Gets the current network type.

API Name: getNetworkType

Payload: {} (no parameters)

Return Value:

networkStatusChange.subscribe

Starts listening for network status changes.

API Name: networkStatusChange.subscribe

Payload: {} (no parameters)

Return Value:

Subscription Event Data:

Implementation: Based on NetInfo real-time push.

networkStatusChange.unsubscribe

Stops listening for network status changes.

API Name: networkStatusChange.unsubscribe

Payload:

Return Value: null

Sensors

All sensor subscription APIs support custom sampling intervals.

accelerometerChange.subscribe / unsubscribe

Accelerometer data listening.

API Name: accelerometerChange.subscribe / accelerometerChange.unsubscribe

Subscribe Payload:

Subscription Event Data:

Unsubscribe Payload:

gyroscopeChange.subscribe / unsubscribe

Gyroscope data listening.

API Name: gyroscopeChange.subscribe / gyroscopeChange.unsubscribe

Subscribe Payload / Event Data: Same as accelerometer.

magnetometerChange.subscribe / unsubscribe

Magnetometer data listening.

API Name: magnetometerChange.subscribe / magnetometerChange.unsubscribe

Subscribe Payload / Event Data: Same as accelerometer.

barometerChange.subscribe / unsubscribe

Barometer data listening.

API Name: barometerChange.subscribe / barometerChange.unsubscribe

Subscribe Payload: {} (interval configuration not supported)

Subscription Event Data:

Screenshot Event

userCaptureScreen.subscribe / unsubscribe

Listens for user screenshot operations.

API Name: userCaptureScreen.subscribe / userCaptureScreen.unsubscribe

Subscribe Payload: {} (no parameters)

Return Value:

Subscription Event Data: null (only notifies that a screenshot occurred, no additional data).

Implementation: Based on ScreenshotAware listener.

Miniapp Update

getMiniAppUpdateInfo

Gets installation/available version information for the miniapp.

API Name: getMiniAppUpdateInfo

Timeout: 15000ms

Payload: {} (no parameters)

Return Value:

applyMiniAppUpdate

Downloads and installs the latest available bundle.

API Name: applyMiniAppUpdate

Timeout: 120000ms

Payload: {} (no parameters)

Return Value: Same as getMiniAppUpdateInfo.

File Transfer (Task API)

Task APIs support progress callbacks and abort operations. Calling start returns a taskId, and abort cancels the task.

downloadFile.start

Starts a file download task.

API Name: downloadFile.start

Payload:

Return Value:

Progress Event (channel: task.progress):

Header Event (channel: task.headers):

Completion Result:

// Success
{ ok: true, data: { tempFilePath: string, statusCode: number } }

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

Auto Path Generation: ${TemporaryDirectoryPath}/${Date.now()}_download

Implementation: Based on RNFS.downloadFile.

downloadFile.abort

Aborts a download task.

API Name: downloadFile.abort

Payload:

Return Value: { ok: true, data: null }

uploadFile.start

Starts a file upload task.

API Name: uploadFile.start

Payload:

Return Value:

Progress Event (channel: task.progress):

Completion Result:

// Success
{ ok: true, data: { data: string, statusCode: number } }

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

HTTP Method: POST

Implementation: Based on RNFS.uploadFiles, filename extracted automatically from filePath.

uploadFile.abort

Aborts an upload task.

API Name: uploadFile.abort

Payload:

Return Value: { ok: true, data: null }

Pure Function Exports

The following functions can be called directly and do not follow the Task API flow (no progress callbacks).

downloadFileHost(options)

Simple file download.

async function downloadFileHost(options: {
  url: string;
  header?: Record<string, string>;
  timeout?: number;
  filePath?: string;
}): Promise<{ tempFilePath: string; statusCode: number }>;

uploadFileHost(options)

Simple file upload.

async function uploadFileHost(options: {
  url: string;
  filePath: string;
  name: string;
  header?: Record<string, string>;
  formData?: Record<string, string>;
  timeout?: number;
}): Promise<{ data: string; statusCode: number }>;

saveMediaHost(payload)

Directly saves media to the system photo album.

async function saveMediaHost(payload: {
  url: string;
  type: 'photo' | 'video';
  album?: string;
}): Promise<string>;

Common Error Format

All failed API calls return a unified format:

{
  ok: false,
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  }
}

Default Timeouts