@nebula-rn/host-apis 0.0.1

package/dist/hostApiBridge.d.ts

@@ -0,0 +1,23 @@
+import { createHostApiFailure, createHostApiSuccess } from '@nebula-rn/sdk';
+import type { NebulaApiInvokeResult } from '@nebula-rn/sdk';
+export type HostApiEventMessage<TPayload = unknown> = {
+    __nebulaApiEvent: 'v1';
+    apiName: string;
+    channel: string;
+    subscriptionId?: string;
+    taskId?: string;
+    payload?: TPayload;
+};
+export declare function createHostBridgeId(prefix: string): string;
+export declare function emitHostApiEvent<TPayload>(appId: string, message: HostApiEventMessage<TPayload>): Promise<void>;
+export declare function createSubscriptionStartResult(subscriptionId: string): NebulaApiInvokeResult<{
+    subscriptionId: string;
+}>;
+export declare function createTaskStartResult(taskId: string): NebulaApiInvokeResult<{
+    taskId: string;
+}>;
+export declare function emitSubscriptionEvent<TPayload>(appId: string, apiName: string, subscriptionId: string, payload: TPayload): Promise<void>;
+export declare function emitTaskProgress<TPayload>(appId: string, apiName: string, taskId: string, payload: TPayload): Promise<void>;
+export declare function emitTaskHeaders<TPayload>(appId: string, apiName: string, taskId: string, payload: TPayload): Promise<void>;
+export declare function emitTaskResult<TPayload>(appId: string, apiName: string, taskId: string, result: NebulaApiInvokeResult<TPayload>): Promise<void>;
+export { createHostApiFailure, createHostApiSuccess };

package/dist/hostApiBridge.js

@@ -0,0 +1,54 @@
+import { NebulaAPI, createHostApiFailure, createHostApiSuccess, } from '@nebula-rn/sdk';
+export function createHostBridgeId(prefix) {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export async function emitHostApiEvent(appId, message) {
+    await NebulaAPI.postMessageToMiniApp(appId, message);
+}
+export function createSubscriptionStartResult(subscriptionId) {
+    return createHostApiSuccess({
+        subscriptionId,
+    });
+}
+export function createTaskStartResult(taskId) {
+    return createHostApiSuccess({
+        taskId,
+    });
+}
+export function emitSubscriptionEvent(appId, apiName, subscriptionId, payload) {
+    return emitHostApiEvent(appId, {
+        __nebulaApiEvent: 'v1',
+        apiName,
+        channel: 'subscription',
+        subscriptionId,
+        payload,
+    });
+}
+export function emitTaskProgress(appId, apiName, taskId, payload) {
+    return emitHostApiEvent(appId, {
+        __nebulaApiEvent: 'v1',
+        apiName,
+        channel: 'task.progress',
+        taskId,
+        payload,
+    });
+}
+export function emitTaskHeaders(appId, apiName, taskId, payload) {
+    return emitHostApiEvent(appId, {
+        __nebulaApiEvent: 'v1',
+        apiName,
+        channel: 'task.headers',
+        taskId,
+        payload,
+    });
+}
+export function emitTaskResult(appId, apiName, taskId, result) {
+    return emitHostApiEvent(appId, {
+        __nebulaApiEvent: 'v1',
+        apiName,
+        channel: 'task.result',
+        taskId,
+        payload: result,
+    });
+}
+export { createHostApiFailure, createHostApiSuccess };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { previewImageHostApi } from './PreviewImageHostBridge';
+import { scanCodeHostApi } from './ScanCodeHostBridge';
+import { coreHostApis, saveMediaHost } from './coreHostApis';
+import { downloadFileHostApi, downloadFileHost, uploadFileHostApi, uploadFileHost } from './taskHosts';
+export { previewImageHostApi, scanCodeHostApi, coreHostApis, saveMediaHost };
+export { downloadFileHostApi, downloadFileHost, uploadFileHostApi, uploadFileHost, };
+export declare const defaultHostApis: import("@nebula-rn/sdk").NebulaHostFeature[];

package/dist/index.js

@@ -0,0 +1,11 @@
+import { previewImageHostApi } from './PreviewImageHostBridge';
+import { scanCodeHostApi } from './ScanCodeHostBridge';
+import { coreHostApis, saveMediaHost } from './coreHostApis';
+import { downloadFileHostApi, downloadFileHost, uploadFileHostApi, uploadFileHost, } from './taskHosts';
+export { previewImageHostApi, scanCodeHostApi, coreHostApis, saveMediaHost };
+export { downloadFileHostApi, downloadFileHost, uploadFileHostApi, uploadFileHost, };
+export const defaultHostApis = [
+    scanCodeHostApi,
+    previewImageHostApi,
+    ...coreHostApis,
+];

package/dist/previewImageRuntime.d.ts

@@ -0,0 +1,8 @@
+export type PreviewImageRequest = {
+    urls: string[];
+    current?: string;
+    showMenu?: boolean;
+    saveMediaText?: string;
+    cancelText?: string;
+};
+export declare const previewImageChannel: import("@nebula-rn/sdk").HostModalChannel<PreviewImageRequest>;

package/dist/previewImageRuntime.js

@@ -0,0 +1,2 @@
+import { createHostModalChannel } from '@nebula-rn/sdk';
+export const previewImageChannel = createHostModalChannel();

package/dist/scanCodeRuntime.d.ts

@@ -0,0 +1,5 @@
+export type ScanCodeRequest = {
+    onlyFromCamera?: boolean;
+    scanTypes: string[];
+};
+export declare const scanCodeChannel: import("@nebula-rn/sdk").HostModalChannel<ScanCodeRequest>;

package/dist/scanCodeRuntime.js

@@ -0,0 +1,2 @@
+import { createHostModalChannel } from '@nebula-rn/sdk';
+export const scanCodeChannel = createHostModalChannel();

package/dist/taskHosts.d.ts

@@ -0,0 +1,27 @@
+type DownloadFileHostOption = {
+    url: string;
+    header?: Record<string, string>;
+    timeout?: number;
+    filePath?: string;
+};
+type DownloadFileHostResult = {
+    tempFilePath: string;
+    statusCode: number;
+};
+type UploadFileHostOption = {
+    url: string;
+    filePath: string;
+    name: string;
+    header?: Record<string, string>;
+    formData?: Record<string, string>;
+    timeout?: number;
+};
+type UploadFileHostResult = {
+    data: string;
+    statusCode: number;
+};
+export declare const downloadFileHost: (options: DownloadFileHostOption) => Promise<DownloadFileHostResult>;
+export declare const uploadFileHost: (options: UploadFileHostOption) => Promise<UploadFileHostResult>;
+export declare const downloadFileHostApi: import("@nebula-rn/sdk").NebulaHostFeature[];
+export declare const uploadFileHostApi: import("@nebula-rn/sdk").NebulaHostFeature[];
+export {};

package/dist/taskHosts.js

@@ -0,0 +1,204 @@
+import * as RNFS from '@dr.pogodin/react-native-fs';
+import { createHostApiFeature } from '@nebula-rn/sdk';
+import { createTaskStartResult, emitTaskHeaders, emitTaskProgress, emitTaskResult, } from './hostApiBridge';
+const activeDownloads = new Map();
+const activeUploads = new Map();
+const TASK_API_DESCRIPTIONS = {
+    'downloadFile.start': {
+        summary: 'Start a host-managed file download task with progress events.',
+        tags: ['file', 'task', 'network'],
+    },
+    'downloadFile.abort': {
+        summary: 'Abort an in-flight host download task by task id.',
+        tags: ['file', 'task', 'network'],
+    },
+    'uploadFile.start': {
+        summary: 'Start a host-managed file upload task with progress events.',
+        tags: ['file', 'task', 'network'],
+    },
+    'uploadFile.abort': {
+        summary: 'Abort an in-flight host upload task by task id.',
+        tags: ['file', 'task', 'network'],
+    },
+};
+export const downloadFileHost = async (options) => {
+    const { url, header = {}, timeout = 60000, filePath } = options;
+    const destPath = filePath || `${RNFS.TemporaryDirectoryPath}/${Date.now()}_download`;
+    const result = await RNFS.downloadFile({
+        fromUrl: url,
+        toFile: destPath,
+        headers: header,
+        connectionTimeout: timeout,
+        readTimeout: timeout,
+    }).promise;
+    return {
+        tempFilePath: destPath,
+        statusCode: result.statusCode,
+    };
+};
+export const uploadFileHost = async (options) => {
+    const nativeTask = RNFS.uploadFiles({
+        toUrl: options.url,
+        files: [
+            {
+                name: options.name,
+                filename: options.filePath.split('/').pop() || 'file',
+                filepath: options.filePath,
+            },
+        ],
+        headers: options.header ?? {},
+        fields: options.formData ?? {},
+        method: 'POST',
+    });
+    const result = await nativeTask.promise;
+    return {
+        data: result.body,
+        statusCode: result.statusCode,
+    };
+};
+export const downloadFileHostApi = [
+    createHostApiFeature({
+        apiName: 'downloadFile.start',
+        description: TASK_API_DESCRIPTIONS['downloadFile.start'],
+        async handle(payload, context) {
+            const taskId = `download-${Date.now()}-${Math.random()
+                .toString(36)
+                .slice(2, 10)}`;
+            const options = payload;
+            const destPath = options.filePath ||
+                `${RNFS.TemporaryDirectoryPath}/${Date.now()}_download`;
+            const nativeTask = RNFS.downloadFile({
+                fromUrl: options.url,
+                toFile: destPath,
+                headers: options.header ?? {},
+                connectionTimeout: options.timeout ?? 60000,
+                readTimeout: options.timeout ?? 60000,
+                begin: res => {
+                    emitTaskHeaders(context.appId, 'downloadFile', taskId, {
+                        header: res.headers,
+                    }).catch(() => { });
+                },
+                progress: res => {
+                    emitTaskProgress(context.appId, 'downloadFile', taskId, {
+                        progress: Math.floor((res.bytesWritten / res.contentLength) * 100),
+                        totalBytesWritten: res.bytesWritten,
+                        totalBytesExpectedToWrite: res.contentLength,
+                    }).catch(() => { });
+                },
+            });
+            activeDownloads.set(taskId, nativeTask.jobId);
+            nativeTask.promise
+                .then(res => emitTaskResult(context.appId, 'downloadFile', taskId, {
+                ok: true,
+                data: {
+                    tempFilePath: destPath,
+                    statusCode: res.statusCode,
+                },
+            }))
+                .catch(error => emitTaskResult(context.appId, 'downloadFile', taskId, {
+                ok: false,
+                error: {
+                    code: 'DOWNLOAD_FAILED',
+                    message: error instanceof Error
+                        ? error.message
+                        : 'downloadFile:fail host download failed',
+                },
+            }))
+                .finally(() => {
+                activeDownloads.delete(taskId);
+            });
+            return createTaskStartResult(taskId);
+        },
+    }),
+    createHostApiFeature({
+        apiName: 'downloadFile.abort',
+        description: TASK_API_DESCRIPTIONS['downloadFile.abort'],
+        async handle(payload) {
+            const taskId = String(payload.taskId ?? '');
+            const jobId = activeDownloads.get(taskId);
+            if (jobId) {
+                RNFS.stopDownload(jobId);
+                activeDownloads.delete(taskId);
+            }
+            return {
+                ok: true,
+                data: null,
+            };
+        },
+    }),
+];
+export const uploadFileHostApi = [
+    createHostApiFeature({
+        apiName: 'uploadFile.start',
+        description: TASK_API_DESCRIPTIONS['uploadFile.start'],
+        async handle(payload, context) {
+            const taskId = `upload-${Date.now()}-${Math.random()
+                .toString(36)
+                .slice(2, 10)}`;
+            const options = payload;
+            const nativeTask = RNFS.uploadFiles({
+                toUrl: options.url,
+                files: [
+                    {
+                        name: options.name,
+                        filename: options.filePath.split('/').pop() || 'file',
+                        filepath: options.filePath,
+                    },
+                ],
+                headers: options.header ?? {},
+                fields: options.formData ?? {},
+                method: 'POST',
+                progress: res => {
+                    emitTaskProgress(context.appId, 'uploadFile', taskId, {
+                        progress: Math.floor((res.totalBytesSent / res.totalBytesExpectedToSend) * 100),
+                        totalBytesSent: res.totalBytesSent,
+                        totalBytesExpectedToSend: res.totalBytesExpectedToSend,
+                    }).catch(() => { });
+                },
+            });
+            activeUploads.set(taskId, nativeTask.jobId);
+            nativeTask.promise
+                .then(res => Promise.all([
+                emitTaskHeaders(context.appId, 'uploadFile', taskId, {
+                    header: res.headers,
+                }),
+                emitTaskResult(context.appId, 'uploadFile', taskId, {
+                    ok: true,
+                    data: {
+                        data: res.body,
+                        statusCode: res.statusCode,
+                    },
+                }),
+            ]))
+                .catch(error => emitTaskResult(context.appId, 'uploadFile', taskId, {
+                ok: false,
+                error: {
+                    code: 'UPLOAD_FAILED',
+                    message: error instanceof Error
+                        ? error.message
+                        : 'uploadFile:fail host upload failed',
+                },
+            }))
+                .finally(() => {
+                activeUploads.delete(taskId);
+            });
+            return createTaskStartResult(taskId);
+        },
+    }),
+    createHostApiFeature({
+        apiName: 'uploadFile.abort',
+        description: TASK_API_DESCRIPTIONS['uploadFile.abort'],
+        async handle(payload) {
+            const taskId = String(payload.taskId ?? '');
+            const jobId = activeUploads.get(taskId);
+            if (jobId) {
+                RNFS.stopUpload(jobId);
+                activeUploads.delete(taskId);
+            }
+            return {
+                ok: true,
+                data: null,
+            };
+        },
+    }),
+];

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nebula-rn/host-apis",
+  "version": "0.0.1",
+  "description": "Official Nebula host API feature bundle",
+  "author": "Hector Zhuang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hector-Zhuang/nebula.git",
+    "directory": "packages/host-apis"
+  },
+  "bugs": {
+    "url": "https://github.com/Hector-Zhuang/nebula/issues"
+  },
+  "homepage": "https://github.com/Hector-Zhuang/nebula/tree/main/packages/host-apis#readme",
+  "keywords": ["nebula", "superapp", "miniapp", "react-native"],
+  "main": "./dist/index.js",
+  "react-native": "./src/index.ts",
+  "source": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "src", "README.md"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "lint": "eslint src --ext .ts,.tsx"
+  },
+  "dependencies": {
+    "@bam.tech/react-native-image-resizer": "^3.0.11",
+    "@dr.pogodin/react-native-fs": "^2.37.0",
+    "@nebula-rn/sdk": "^0.0.1",
+    "@react-native-camera-roll/camera-roll": "^7.10.2",
+    "@react-native-clipboard/clipboard": "^1.16.3",
+    "@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-picker": "^8.2.1",
+    "react-native-image-zoom-viewer": "^3.0.1",
+    "react-native-mmkv": "^4.2.0",
+    "react-native-safe-area-context": "^5.5.2",
+    "react-native-screenshot-aware": "^2.0.0",
+    "react-native-sensors": "^7.3.6",
+    "react-native-vision-camera": "^4.7.3"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-native": ">=0.83"
+  }
+}

package/src/NebulaHostPreviewImageModal.tsx

@@ -0,0 +1,119 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { ActivityIndicator, StyleSheet, View } from 'react-native';
+import ImageViewer from 'react-native-image-zoom-viewer';
+import { NebulaAPI } from '@nebula-rn/sdk';
+import { createHostApiFailure, createHostApiSuccess } from './hostApiBridge';
+import { previewImageChannel } from './previewImageRuntime';
+import { saveMediaHost } from './coreHostApis';
+import { downloadFileHost } from './taskHosts';
+
+function PreviewImageLoading(): React.ReactElement {
+  return (
+    <View style={styles.loadingContainer}>
+      <ActivityIndicator size="large" color="#999" />
+    </View>
+  );
+}
+
+function renderPreviewImageLoading() {
+  return <PreviewImageLoading />;
+}
+
+export default function NebulaHostPreviewImageModal(): React.ReactElement | null {
+  const [request, setRequest] = useState(previewImageChannel.getCurrent());
+  const didCloseRef = useRef(false);
+
+  useEffect(() => {
+    return previewImageChannel.subscribe(nextRequest => {
+      didCloseRef.current = false;
+      setRequest(nextRequest);
+    });
+  }, []);
+
+  const imageUrls = useMemo(
+    () => request?.urls.map(url => ({ url })) ?? [],
+    [request],
+  );
+
+  if (!request) {
+    return null;
+  }
+
+  const initialIndex = request.current
+    ? request.urls.indexOf(request.current)
+    : 0;
+  const index = initialIndex === -1 ? 0 : initialIndex;
+
+  const close = (
+    result:
+      | ReturnType<typeof createHostApiSuccess<{ dismissed: boolean }>>
+      | ReturnType<typeof createHostApiFailure> = createHostApiSuccess({
+      dismissed: true,
+    }),
+  ) => {
+    if (didCloseRef.current) {
+      return;
+    }
+    didCloseRef.current = true;
+    NebulaAPI.dismissHostModal()
+      .catch(() => {})
+      .finally(() => {
+        previewImageChannel.settle(result);
+      });
+  };
+
+  return (
+    <View style={styles.container}>
+      <ImageViewer
+        imageUrls={imageUrls}
+        index={index}
+        onCancel={() => close()}
+        onClick={() => close()}
+        onSwipeDown={() => close()}
+        enableSwipeDown
+        useNativeDriver
+        loadingRender={renderPreviewImageLoading}
+        onSave={async uri => {
+          try {
+            const download = await downloadFileHost({
+              url: uri,
+            });
+            await saveMediaHost({
+              url: download.tempFilePath,
+              type: 'photo',
+            });
+          } catch (error) {
+            close(
+              createHostApiFailure(
+                'PREVIEW_IMAGE_SAVE_FAILED',
+                error instanceof Error
+                  ? error.message
+                  : 'previewImage:fail unable to save image',
+              ),
+            );
+          }
+        }}
+        menuContext={
+          request.showMenu === false
+            ? undefined
+            : {
+                saveToLocal: request.saveMediaText ?? 'Save Image',
+                cancel: request.cancelText ?? 'Cancel',
+              }
+        }
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#000',
+  },
+  loadingContainer: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+});