@nebula-rn/sdk 0.0.1

package/dist/hostApi.js

@@ -0,0 +1,185 @@
+import React from 'react';
+import { AppRegistry } from 'react-native';
+import { NebulaAPI } from './NebulaAPI';
+export function createHostApiFailure(code, message) {
+    return {
+        ok: false,
+        error: {
+            code,
+            message,
+        },
+    };
+}
+export function createHostApiSuccess(data) {
+    return {
+        ok: true,
+        data,
+    };
+}
+export function createHostModalChannel() {
+    let pendingRequest = null;
+    const listeners = new Set();
+    const notify = () => {
+        listeners.forEach(listener => listener(pendingRequest));
+    };
+    return {
+        clear() {
+            pendingRequest = null;
+            notify();
+        },
+        getCurrent() {
+            return pendingRequest;
+        },
+        open(request) {
+            return new Promise(resolve => {
+                pendingRequest = {
+                    ...request,
+                    resolve: result => {
+                        pendingRequest = null;
+                        notify();
+                        resolve(result);
+                    },
+                };
+                notify();
+            });
+        },
+        settle(result) {
+            pendingRequest?.resolve(result);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            listener(pendingRequest);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+function getHostModalModuleName(apiName) {
+    const normalizedName = apiName.replace(/[^a-zA-Z0-9_]+/g, '_');
+    return `NebulaHostModal_${normalizedName}`;
+}
+function createHostModalApiHandler({ apiName, channel, createRequest, modalProps, onBeforeOpen, version = '1.0', description, }) {
+    const modalModuleName = getHostModalModuleName(apiName);
+    let requestInFlight = false;
+    return {
+        version,
+        description,
+        handle: async (payload) => {
+            if (requestInFlight) {
+                return createHostApiFailure('SCAN_FAILED', `${apiName}:fail another request is already in progress`);
+            }
+            const typedPayload = payload;
+            requestInFlight = true;
+            try {
+                const precheckResult = onBeforeOpen
+                    ? await onBeforeOpen(typedPayload)
+                    : null;
+                if (precheckResult) {
+                    return precheckResult;
+                }
+                const request = createRequest(typedPayload);
+                const resultPromise = channel.open(request);
+                const resolvedModalProps = typeof modalProps === 'function'
+                    ? modalProps(typedPayload, request)
+                    : (modalProps ?? {});
+                await NebulaAPI.presentHostModal(modalModuleName, {
+                    __transparentBackground: true,
+                    ...resolvedModalProps,
+                });
+                return await resultPromise;
+            }
+            catch (error) {
+                channel.settle(createHostApiFailure('SCAN_FAILED', `${apiName}:fail host modal flow interrupted`));
+                return createHostApiFailure('SCAN_FAILED', error instanceof Error
+                    ? error.message
+                    : `${apiName}:fail unable to present host modal`);
+            }
+            finally {
+                requestInFlight = false;
+            }
+        },
+        cleanup: () => {
+            requestInFlight = false;
+        },
+    };
+}
+export function registerHostModalApi({ apiName, component, channel, createRequest, modalProps, onBeforeOpen, onUnmountErrorMessage, version = '1.0', description, }) {
+    const modalModuleName = getHostModalModuleName(apiName);
+    AppRegistry.registerComponent(modalModuleName, () => component);
+    const handler = createHostModalApiHandler({
+        apiName,
+        channel,
+        createRequest,
+        modalProps,
+        onBeforeOpen,
+        version,
+        description,
+    });
+    NebulaAPI.registerApiHandler(apiName, {
+        version: handler.version,
+        description: handler.description,
+        handle: handler.handle,
+    });
+    return () => {
+        NebulaAPI.unregisterApiHandler(apiName);
+        handler.cleanup();
+        channel.settle(createHostApiFailure('SCAN_FAILED', onUnmountErrorMessage ??
+            `${apiName}:fail host modal was unmounted before completion`));
+        NebulaAPI.dismissHostModal().catch(() => { });
+    };
+}
+export function createHostApiFeature({ apiName, supported, version = '1.0', description, handle, }) {
+    return {
+        name: apiName,
+        description,
+        register() {
+            NebulaAPI.registerApiHandler(apiName, {
+                version,
+                supported,
+                description,
+                handle,
+            });
+            return () => {
+                NebulaAPI.unregisterApiHandler(apiName);
+            };
+        },
+    };
+}
+export function createMockHostApiFeature({ apiName, version = '1.0.0', description, delayMs = 0, result, error, }) {
+    return createHostApiFeature({
+        apiName,
+        version,
+        description,
+        handle: async (payload) => {
+            if (delayMs > 0) {
+                await new Promise(resolve => setTimeout(resolve, delayMs));
+            }
+            if (error) {
+                const resolvedError = typeof error === 'function' ? await error(payload) : error;
+                return createHostApiFailure(resolvedError.code, resolvedError.message);
+            }
+            const resolvedResult = typeof result === 'function' ? await result(payload) : result;
+            return createHostApiSuccess(typeof resolvedResult === 'undefined' ? null : resolvedResult);
+        },
+    });
+}
+export function createHostModalApiFeature(options) {
+    return {
+        name: options.apiName,
+        description: options.description,
+        register() {
+            return registerHostModalApi(options);
+        },
+    };
+}
+export function createHostModalApiBridge(options) {
+    return function HostModalApiBridge() {
+        React.useEffect(() => registerHostModalApi(options), []);
+        return null;
+    };
+}
+export function registerHostModalComponent(moduleName, component) {
+    AppRegistry.registerComponent(moduleName, () => component);
+    return moduleName;
+}

package/dist/hostProtocol.d.ts

@@ -0,0 +1,9 @@
+import type { NebulaHostApiDescriptionMap, NebulaHostApiHandler, NebulaHostCapabilityMap, NebulaProtocolResponse } from './nebulaTypes';
+export declare function resolveHostCapabilities(): Promise<NebulaHostCapabilityMap>;
+export declare function resolveHostApiDescriptions(): NebulaHostApiDescriptionMap;
+export declare function startHostApiServer(postMessageToMiniApp: (appId: string, message: NebulaProtocolResponse) => Promise<{
+    errMsg: string;
+}>): void;
+export declare function stopHostApiServer(): void;
+export declare function registerHostApiHandler(apiName: string, handler: NebulaHostApiHandler): void;
+export declare function unregisterHostApiHandler(apiName: string): void;

package/dist/hostProtocol.js

@@ -0,0 +1,153 @@
+import { addNebulaEventListener, isProtocolRequest, NEBULA_HOST_MESSAGE_EVENT, } from './nebulaNative';
+const hostApiRegistry = new Map();
+let hostApiServerStarted = false;
+let hostApiServerUnsubscribe = null;
+export async function resolveHostCapabilities() {
+    const entries = await Promise.all(Array.from(hostApiRegistry.entries()).map(async ([apiName, handler]) => {
+        const supported = typeof handler.supported === 'function'
+            ? await handler.supported()
+            : (handler.supported ?? true);
+        return [
+            apiName,
+            {
+                version: handler.version,
+                supported,
+            },
+        ];
+    }));
+    return entries.reduce((capabilities, entry) => {
+        capabilities[entry[0]] = entry[1];
+        return capabilities;
+    }, {});
+}
+export function resolveHostApiDescriptions() {
+    return Array.from(hostApiRegistry.entries()).reduce((descriptions, [apiName, handler]) => {
+        if (handler.description) {
+            descriptions[apiName] = handler.description;
+        }
+        return descriptions;
+    }, {});
+}
+export function startHostApiServer(postMessageToMiniApp) {
+    if (hostApiServerStarted) {
+        return;
+    }
+    const unsubscribe = addNebulaEventListener(NEBULA_HOST_MESSAGE_EVENT, event => {
+        const message = event.message;
+        if (!isProtocolRequest(message)) {
+            return;
+        }
+        const reply = async (response) => {
+            await postMessageToMiniApp(event.appId, response);
+        };
+        if (message.kind === 'getCapabilities') {
+            resolveHostCapabilities()
+                .then(capabilities => reply({
+                __nebulaProtocol: 'api.v1',
+                kind: 'capabilities',
+                requestId: message.requestId,
+                data: {
+                    bridgeVersion: '1.0.0',
+                    capabilities,
+                },
+            }))
+                .catch(error => {
+                console.error('[Nebula] Failed to resolve host capabilities', error);
+            });
+            return;
+        }
+        if (message.kind === 'getApiDescriptions') {
+            reply({
+                __nebulaProtocol: 'api.v1',
+                kind: 'apiDescriptions',
+                requestId: message.requestId,
+                data: resolveHostApiDescriptions(),
+            }).catch(error => {
+                console.error('[Nebula] Failed to resolve host API descriptions', error);
+            });
+            return;
+        }
+        if (message.kind !== 'invoke') {
+            return;
+        }
+        const handler = hostApiRegistry.get(message.api);
+        if (!handler) {
+            reply({
+                __nebulaProtocol: 'api.v1',
+                kind: 'invokeResult',
+                requestId: message.requestId,
+                result: {
+                    ok: false,
+                    error: {
+                        code: 'UNSUPPORTED_API',
+                        message: `${message.api} is not supported by the current host`,
+                    },
+                },
+            }).catch(error => {
+                console.error('[Nebula] Failed to send unsupported API reply', error);
+            });
+            return;
+        }
+        const resolveSupported = async () => typeof handler.supported === 'function'
+            ? handler.supported()
+            : (handler.supported ?? true);
+        Promise.resolve(resolveSupported())
+            .then(async (supported) => {
+            if (!supported) {
+                await reply({
+                    __nebulaProtocol: 'api.v1',
+                    kind: 'invokeResult',
+                    requestId: message.requestId,
+                    result: {
+                        ok: false,
+                        error: {
+                            code: 'UNSUPPORTED_API',
+                            message: `${message.api} is not supported by the current host`,
+                        },
+                    },
+                });
+                return;
+            }
+            const result = await handler.handle(message.payload ?? {}, {
+                appId: event.appId,
+                requestId: message.requestId,
+                version: message.version,
+            });
+            await reply({
+                __nebulaProtocol: 'api.v1',
+                kind: 'invokeResult',
+                requestId: message.requestId,
+                result,
+            });
+        })
+            .catch(async (error) => {
+            await reply({
+                __nebulaProtocol: 'api.v1',
+                kind: 'invokeResult',
+                requestId: message.requestId,
+                result: {
+                    ok: false,
+                    error: {
+                        code: 'INTERNAL_ERROR',
+                        message: error instanceof Error
+                            ? error.message
+                            : 'Unexpected host error',
+                    },
+                },
+            });
+        });
+    });
+    hostApiServerUnsubscribe = unsubscribe ?? null;
+    hostApiServerStarted = true;
+}
+export function stopHostApiServer() {
+    hostApiServerUnsubscribe?.();
+    hostApiServerUnsubscribe = null;
+    hostApiServerStarted = false;
+}
+export function registerHostApiHandler(apiName, handler) {
+    hostApiRegistry.set(apiName, handler);
+}
+export function unregisterHostApiHandler(apiName) {
+    hostApiRegistry.delete(apiName);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { NebulaAPI, Miniapp, createMiniAppPage, usePageOnHide, usePageOnLoad, usePageOnReady, usePageOnShow, usePageOnUnload, } from './NebulaAPI';
+export { createHostApiFeature, createMockHostApiFeature, createHostApiFailure, createHostApiSuccess, createHostModalApiFeature, registerHostModalApi, createHostModalApiBridge, createHostModalChannel, registerHostModalComponent, } from './hostApi';
+export type { HostModalChannel, CreateMockHostApiOptions, NebulaHostFeature, RegisterHostApiOptions, RegisterHostModalApiOptions, } from './hostApi';
+export { definePageConfig } from './pageConfig';
+export type { NebulaApiExampleDescriptor, NebulaApiFieldDescriptor, MiniappLoadingProps, MiniappLoadingStatus, MiniAppUpdateInfo, MiniAppUpdateStrategy, MiniAppVersionType, NebulaApiError, NebulaApiInvokeResult, NebulaHostApiDescription, NebulaHostApiDescriptionMap, NebulaHostApiHandler, NebulaHostCapabilityDescriptor, NebulaHostCapabilityMap, NebulaNativeCapabilitiesResult, NebulaNativeCapabilityMap, NebulaPageStyle, } from './NebulaAPI';
+export type { MiniAppPageConfig } from './pageConfig';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { NebulaAPI, Miniapp, createMiniAppPage, usePageOnHide, usePageOnLoad, usePageOnReady, usePageOnShow, usePageOnUnload, } from './NebulaAPI';
+export { createHostApiFeature, createMockHostApiFeature, createHostApiFailure, createHostApiSuccess, createHostModalApiFeature, registerHostModalApi, createHostModalApiBridge, createHostModalChannel, registerHostModalComponent, } from './hostApi';
+export { definePageConfig } from './pageConfig';

package/dist/miniappLoading.d.ts

@@ -0,0 +1,18 @@
+import type { InstalledMiniAppInfo, MiniappLoadingProps, MiniappLoadingResolveContext, MiniappLoadingResolvedProps, MiniappLoadingStatus } from './nebulaTypes';
+type MiniappLoadingState = {
+    appId: string | null;
+    mode: 'development' | 'production';
+    status: MiniappLoadingStatus;
+    title?: string | null;
+    icon?: MiniappLoadingProps['icon'];
+    extraData?: MiniappLoadingProps['extraData'];
+    installedInfo?: InstalledMiniAppInfo | null;
+    errorMessage?: string | null;
+    visible: boolean;
+};
+export declare function configureMiniappLoadingComponent(component: React.ComponentType<MiniappLoadingProps> | null, resolveProps?: ((context: MiniappLoadingResolveContext) => MiniappLoadingResolvedProps) | null, delayMs?: number | null): void;
+export declare function setMiniappLoadingState(nextState: Partial<MiniappLoadingState>): void;
+export declare function hideMiniappLoading(appId?: string | null): void;
+export declare function getMiniappLoadingDelayMs(): number;
+export declare function ensureInternalMiniappLoadingComponentRegistered(): void;
+export {};

package/dist/miniappLoading.js

@@ -0,0 +1,103 @@
+import { AppRegistry } from 'react-native';
+import { NEBULA_INTERNAL_MINIAPP_LOADING_MODULE } from './nebulaNative';
+import { createElement, useEffect, useState } from 'react';
+let miniappLoadingDelayMs = 0;
+let internalMiniappLoadingRegistered = false;
+let miniappLoadingComponent = null;
+let miniappLoadingResolveProps = null;
+let miniappLoadingState = {
+    appId: null,
+    mode: 'production',
+    status: 'loading',
+    title: null,
+    icon: null,
+    extraData: null,
+    installedInfo: null,
+    errorMessage: null,
+    visible: false,
+};
+const miniappLoadingListeners = new Set();
+function emitMiniappLoadingState() {
+    miniappLoadingListeners.forEach(listener => listener());
+}
+export function configureMiniappLoadingComponent(component, resolveProps, delayMs) {
+    miniappLoadingComponent = component;
+    miniappLoadingResolveProps = resolveProps ?? null;
+    miniappLoadingDelayMs =
+        typeof delayMs === 'number' && Number.isFinite(delayMs)
+            ? Math.max(0, Math.round(delayMs))
+            : 0;
+}
+export function setMiniappLoadingState(nextState) {
+    miniappLoadingState = {
+        ...miniappLoadingState,
+        ...nextState,
+    };
+    emitMiniappLoadingState();
+}
+export function hideMiniappLoading(appId) {
+    if (appId &&
+        miniappLoadingState.appId &&
+        miniappLoadingState.appId !== appId) {
+        return;
+    }
+    setMiniappLoadingState({
+        visible: false,
+        status: 'ready',
+        title: null,
+        icon: null,
+        extraData: null,
+        installedInfo: null,
+        errorMessage: null,
+    });
+}
+export function getMiniappLoadingDelayMs() {
+    return miniappLoadingDelayMs;
+}
+export function ensureInternalMiniappLoadingComponentRegistered() {
+    if (internalMiniappLoadingRegistered) {
+        return;
+    }
+    AppRegistry.registerComponent(NEBULA_INTERNAL_MINIAPP_LOADING_MODULE, () => {
+        const NebulaInternalMiniappLoading = () => {
+            const [, forceUpdate] = useState(0);
+            useEffect(() => {
+                const listener = () => forceUpdate(value => value + 1);
+                miniappLoadingListeners.add(listener);
+                return () => {
+                    miniappLoadingListeners.delete(listener);
+                };
+            }, []);
+            if (!miniappLoadingState.visible || !miniappLoadingState.appId) {
+                return null;
+            }
+            const Component = miniappLoadingComponent;
+            if (!Component) {
+                return null;
+            }
+            const resolvedProps = miniappLoadingResolveProps
+                ? miniappLoadingResolveProps({
+                    appId: miniappLoadingState.appId,
+                    mode: miniappLoadingState.mode,
+                    status: miniappLoadingState.status,
+                    title: miniappLoadingState.title,
+                    icon: miniappLoadingState.icon,
+                    extraData: miniappLoadingState.extraData,
+                    errorMessage: miniappLoadingState.errorMessage,
+                    installedInfo: miniappLoadingState.installedInfo,
+                })
+                : null;
+            return createElement(Component, {
+                appId: miniappLoadingState.appId,
+                mode: miniappLoadingState.mode,
+                status: miniappLoadingState.status,
+                title: resolvedProps?.title ?? miniappLoadingState.title,
+                icon: resolvedProps?.icon ?? miniappLoadingState.icon,
+                extraData: resolvedProps?.extraData ?? miniappLoadingState.extraData,
+                errorMessage: miniappLoadingState.errorMessage,
+            });
+        };
+        return NebulaInternalMiniappLoading;
+    });
+    internalMiniappLoadingRegistered = true;
+}

package/dist/miniappPage.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+export declare function createMiniAppPage<P extends Record<string, unknown>>(Component: React.ComponentType<P>): React.ComponentType<P>;
+export declare function usePageOnLoad(callback: (params: Record<string, unknown>) => void): void;
+export declare function usePageOnShow(callback: () => void): void;
+export declare function usePageOnReady(callback: () => void): void;
+export declare function usePageOnHide(callback: () => void): void;
+export declare function usePageOnUnload(callback: () => void): void;

package/dist/miniappPage.js

@@ -0,0 +1,93 @@
+import React, { useContext, useEffect, useRef } from 'react';
+import { PAGE_RESERVED_PROP_KEYS } from './nebulaNative';
+import { Miniapp } from './miniappRuntime';
+const MiniAppPageContext = React.createContext(null);
+function extractPageParams(props) {
+    const params = {};
+    for (const key in props) {
+        if (Object.prototype.hasOwnProperty.call(props, key) &&
+            !PAGE_RESERVED_PROP_KEYS.has(key)) {
+            params[key] = props[key];
+        }
+    }
+    return params;
+}
+function usePageLifecycleSubscription(eventType, callback) {
+    const pageContext = useContext(MiniAppPageContext);
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    useEffect(() => {
+        if (!pageContext?.instanceId) {
+            return;
+        }
+        return Miniapp.onPageLifecycle(event => {
+            if (event.type === eventType &&
+                event.instanceId === pageContext.instanceId) {
+                callbackRef.current();
+            }
+        });
+    }, [eventType, pageContext?.instanceId]);
+}
+export function createMiniAppPage(Component) {
+    return function NebulaMiniAppPage(props) {
+        const appId = typeof props.appId === 'string' && props.appId.length > 0
+            ? props.appId
+            : null;
+        useEffect(() => {
+            Miniapp.bootstrap(appId);
+        }, [appId]);
+        const pageContext = {
+            appId,
+            instanceId: typeof props.instanceId === 'string' && props.instanceId.length > 0
+                ? props.instanceId
+                : null,
+            params: extractPageParams(props),
+            routePath: typeof props.__routePath === 'string' ? props.__routePath : '/',
+            routeUrl: typeof props.__routeUrl === 'string' ? props.__routeUrl : '',
+            pageStyle: props.__pageConfig &&
+                typeof props.__pageConfig === 'object' &&
+                !Array.isArray(props.__pageConfig)
+                ? props.__pageConfig
+                : {},
+        };
+        return React.createElement(MiniAppPageContext.Provider, { value: pageContext }, React.createElement(Component, props));
+    };
+}
+export function usePageOnLoad(callback) {
+    const pageContext = useContext(MiniAppPageContext);
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    useEffect(() => {
+        callbackRef.current(pageContext?.params ?? {});
+    }, [pageContext?.instanceId]);
+}
+export function usePageOnShow(callback) {
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    useEffect(() => {
+        callbackRef.current();
+    }, []);
+    usePageLifecycleSubscription('show', callback);
+}
+export function usePageOnReady(callback) {
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    useEffect(() => {
+        const frame = requestAnimationFrame(() => {
+            callbackRef.current();
+        });
+        return () => cancelAnimationFrame(frame);
+    }, []);
+}
+export function usePageOnHide(callback) {
+    usePageLifecycleSubscription('hide', callback);
+}
+export function usePageOnUnload(callback) {
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    useEffect(() => {
+        return () => {
+            callbackRef.current();
+        };
+    }, []);
+}

package/dist/miniappRuntime.d.ts

@@ -0,0 +1,33 @@
+import type { BridgeMessage, HostVisibilityResult, NavigationResult, NebulaApiInvokeResult, NebulaHostApiDescriptionMap, NebulaHostCapabilityMap, NebulaPageStyle, PageLifecycleEvent } from './nebulaTypes';
+export declare function compareCapabilityVersions(left: string, right: string): number;
+export declare class Miniapp {
+    static bootstrap(appId?: string | null): void;
+    static navigateTo(url: string): Promise<NavigationResult>;
+    static redirectTo(url: string): Promise<NavigationResult>;
+    static reLaunch(url: string): Promise<NavigationResult>;
+    static navigateBack(delta?: number): Promise<NavigationResult>;
+    static setPageStyle(style: NebulaPageStyle): Promise<NavigationResult>;
+    static setNavigationBarTitle(title: string): Promise<NavigationResult>;
+    static setNavigationBarColor(options: {
+        backgroundColor?: string;
+        frontColor?: string;
+    }): Promise<NavigationResult>;
+    static getDeviceInfo(): unknown;
+    static getAppId(): string | null;
+    static getSandboxPath(): string;
+    static showToast(title: string): Promise<NavigationResult>;
+    static postMessageToHost(message: Record<string, unknown>): Promise<NavigationResult>;
+    static bringHostToFront(): Promise<HostVisibilityResult>;
+    static restoreMiniApp(token?: string | null): Promise<HostVisibilityResult>;
+    static presentHostModal(moduleName: string, props?: Record<string, unknown>): Promise<NavigationResult>;
+    static dismissHostModal(): Promise<NavigationResult>;
+    static invokeHostApi<TData = unknown>(apiName: string, payload?: Record<string, unknown>, version?: string, timeoutMs?: number): Promise<NebulaApiInvokeResult<TData>>;
+    static getCapabilities(): Promise<{
+        bridgeVersion: string;
+        capabilities: NebulaHostCapabilityMap;
+    }>;
+    static isSupported(apiName: string, minimumVersion?: string): Promise<boolean>;
+    static getHostApiDescriptions(timeoutMs?: number): Promise<NebulaHostApiDescriptionMap>;
+    static onHostMessage(listener: (event: BridgeMessage) => void): () => void;
+    static onPageLifecycle(listener: (event: PageLifecycleEvent) => void): () => void;
+}