@nebula-rn/sdk 0.0.1

package/src/nebulaNative.ts

@@ -0,0 +1,87 @@
+import { NativeEventEmitter, NativeModules } from 'react-native';
+import type { EmitterSubscription, NativeModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+import NebulaNativeModuleSpec from './specs/NativeNebulaModule';
+import type {
+  BridgeMessage,
+  NebulaNativeModuleType,
+  NebulaProtocolRequest,
+  NebulaProtocolResponse,
+} from './nebulaTypes';
+
+const turboNebulaNativeModule =
+  (NebulaNativeModuleSpec as unknown as NebulaNativeModuleType | null) ??
+  TurboModuleRegistry.get<NebulaNativeModuleType>('NebulaNativeModule');
+
+const { NebulaNativeModule: legacyNebulaNativeModule } = NativeModules as {
+  NebulaNativeModule?: NebulaNativeModuleType;
+};
+
+const NebulaNativeModule = turboNebulaNativeModule ?? legacyNebulaNativeModule;
+
+export const nebulaEventEmitter = legacyNebulaNativeModule
+  ? new NativeEventEmitter(legacyNebulaNativeModule as unknown as NativeModule)
+  : null;
+
+export const NEBULA_HOST_MESSAGE_EVENT = 'NebulaHostMessage';
+export const NEBULA_MINI_APP_MESSAGE_EVENT = 'NebulaMiniAppMessage';
+export const NEBULA_PAGE_LIFECYCLE_EVENT = 'NebulaPageLifecycle';
+export const NEBULA_INTERNAL_MINIAPP_LOADING_MODULE =
+  'NebulaInternalMiniappLoading';
+
+export const PAGE_RESERVED_PROP_KEYS = new Set([
+  'appId',
+  'instanceId',
+  'sandboxPath',
+  'title',
+  '__pageConfig',
+  '__routePath',
+  '__routeUrl',
+]);
+
+if (!NebulaNativeModule) {
+  console.warn(
+    '[Nebula] NebulaNativeModule not found. Make sure Nebula framework is integrated.',
+  );
+}
+
+export function getNebulaNativeModule(): NebulaNativeModuleType {
+  if (!NebulaNativeModule) {
+    throw new Error('[Nebula] NebulaNativeModule not available');
+  }
+  return NebulaNativeModule;
+}
+
+export function addNebulaEventListener<TEvent = BridgeMessage>(
+  eventName: string,
+  listener: (event: TEvent) => void,
+): (() => void) | null {
+  if (!nebulaEventEmitter) {
+    return null;
+  }
+  const sub: EmitterSubscription = nebulaEventEmitter.addListener(
+    eventName,
+    listener,
+  );
+  return () => sub.remove();
+}
+
+export function isProtocolRequest(
+  message: Record<string, unknown>,
+): message is NebulaProtocolRequest {
+  return (
+    message.__nebulaProtocol === 'api.v1' &&
+    typeof message.kind === 'string' &&
+    typeof message.requestId === 'string'
+  );
+}
+
+export function isProtocolResponse(
+  message: Record<string, unknown>,
+): message is NebulaProtocolResponse {
+  return (
+    message.__nebulaProtocol === 'api.v1' &&
+    typeof message.kind === 'string' &&
+    typeof message.requestId === 'string'
+  );
+}

package/src/nebulaTypes.ts

@@ -0,0 +1,328 @@
+import type { ReactNode } from 'react';
+import type { TurboModule } from 'react-native';
+import type { NebulaPageStyle } from './specs/NativeNebulaModule';
+
+export type { MiniAppUpdateStrategy } from './specs/NativeNebulaModule';
+export type { NebulaPageStyle } from './specs/NativeNebulaModule';
+export type {
+  NebulaCapabilitiesResult as NebulaNativeCapabilitiesResult,
+  NebulaCapabilityMap as NebulaNativeCapabilityMap,
+} from './specs/NativeNebulaModule';
+
+export type MiniAppResult = {
+  success: boolean;
+  appId: string;
+  mode?: string;
+};
+
+export type InstalledMiniAppsResult = {
+  apps: string[];
+};
+
+export type InstalledMiniAppInfo = {
+  appId: string;
+  mode?: string | null;
+  bundlePath?: string | null;
+  sourceUrl?: string | null;
+  version?: string | null;
+  updateStrategy?: 'auto' | 'manual' | null;
+};
+
+export type InstalledMiniAppInfoResult = {
+  installed: boolean;
+  app?: InstalledMiniAppInfo | null;
+};
+
+export type MiniAppUpdateInfo = {
+  appId: string;
+  currentVersion?: string | null;
+  latestVersion?: string | null;
+  hasUpdate: boolean;
+  updateStrategy: 'auto' | 'manual';
+  mode?: string | null;
+  sourceUrl?: string | null;
+};
+
+export type MiniAppVersionType = 'release' | 'experience';
+
+export type MiniappLoadingStatus = 'installing' | 'loading' | 'ready' | 'error';
+
+export type MiniappLoadingExtraData = Record<string, unknown>;
+
+export type MiniappLoadingProps = {
+  appId: string;
+  mode: 'development' | 'production';
+  status: MiniappLoadingStatus;
+  title?: string | null;
+  icon?: ReactNode;
+  extraData?: MiniappLoadingExtraData | null;
+  errorMessage?: string | null;
+};
+
+export type MiniappLoadingResolveContext = {
+  appId: string;
+  mode: 'development' | 'production';
+  status: MiniappLoadingStatus;
+  title?: string | null;
+  icon?: ReactNode;
+  extraData?: MiniappLoadingExtraData | null;
+  errorMessage?: string | null;
+  installedInfo?: InstalledMiniAppInfo | null;
+};
+
+export type MiniappLoadingResolvedProps = Partial<
+  Pick<MiniappLoadingProps, 'title' | 'icon' | 'extraData'>
+>;
+
+export type ServerBaseURLResult = {
+  serverBaseURL?: string | null;
+};
+
+export type MiniappLoadingDelayResult = {
+  delayMs: number;
+};
+
+export type NavigationResult = {
+  errMsg: string;
+};
+
+export type HostVisibilityResult = {
+  success: boolean;
+  token?: string | null;
+};
+
+export type RegisteredMiniAppManifest = {
+  entryPagePath?: string;
+  pageConfigs?: Record<string, NebulaPageStyle>;
+  pages: Record<string, string>;
+  updateStrategy?: 'auto' | 'manual';
+  version?: string;
+  window?: NebulaPageStyle;
+};
+
+export type BridgeMessage = {
+  appId: string;
+  message: Record<string, unknown>;
+  timestamp?: number;
+};
+
+export type NebulaApiError = {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+};
+
+export type NebulaApiInvokeResult<T = unknown> =
+  | {
+      ok: true;
+      data: T;
+    }
+  | {
+      ok: false;
+      error: NebulaApiError;
+    };
+
+export type NebulaHostCapabilityDescriptor = {
+  supported: boolean;
+  version: string;
+};
+
+export type NebulaHostCapabilityMap = Record<
+  string,
+  NebulaHostCapabilityDescriptor
+>;
+
+export type NebulaApiFieldDescriptor = {
+  name: string;
+  type: string;
+  required?: boolean;
+  description: string;
+};
+
+export type NebulaApiExampleDescriptor = {
+  title: string;
+  code: string;
+};
+
+export type NebulaHostApiDescription = {
+  summary: string;
+  description?: string;
+  params?: NebulaApiFieldDescriptor[];
+  returns?: {
+    type: string;
+    description: string;
+  };
+  tags?: string[];
+  examples?: NebulaApiExampleDescriptor[];
+};
+
+export type NebulaHostApiDescriptionMap = Record<
+  string,
+  NebulaHostApiDescription
+>;
+
+export type NebulaProtocolRequest =
+  | {
+      __nebulaProtocol: 'api.v1';
+      kind: 'getCapabilities';
+      requestId: string;
+    }
+  | {
+      __nebulaProtocol: 'api.v1';
+      kind: 'getApiDescriptions';
+      requestId: string;
+    }
+  | {
+      __nebulaProtocol: 'api.v1';
+      kind: 'invoke';
+      requestId: string;
+      api: string;
+      version?: string;
+      payload?: Record<string, unknown>;
+    };
+
+export type NebulaProtocolResponse =
+  | {
+      __nebulaProtocol: 'api.v1';
+      kind: 'capabilities';
+      requestId: string;
+      data: {
+        bridgeVersion: string;
+        capabilities: NebulaHostCapabilityMap;
+      };
+    }
+  | {
+      __nebulaProtocol: 'api.v1';
+      kind: 'apiDescriptions';
+      requestId: string;
+      data: NebulaHostApiDescriptionMap;
+    }
+  | {
+      __nebulaProtocol: 'api.v1';
+      kind: 'invokeResult';
+      requestId: string;
+      result: NebulaApiInvokeResult;
+    };
+
+export type NebulaHostApiContext = {
+  appId: string;
+  requestId: string;
+  version?: string;
+};
+
+export type NebulaHostApiHandler = {
+  version: string;
+  supported?: boolean | (() => boolean | Promise<boolean>);
+  description?: NebulaHostApiDescription;
+  handle: (
+    payload: Record<string, unknown>,
+    context: NebulaHostApiContext,
+  ) => Promise<NebulaApiInvokeResult> | NebulaApiInvokeResult;
+};
+
+export type PendingProtocolRequest = {
+  reject: (reason?: unknown) => void;
+  resolve: (value: any) => void;
+  timeoutId: ReturnType<typeof setTimeout>;
+};
+
+export type PageLifecycleEvent = {
+  appId: string;
+  instanceId: string;
+  routePath?: string;
+  type: 'show' | 'hide' | 'unload' | 'ready';
+};
+
+export type MiniAppPageContextValue = {
+  appId: string | null;
+  instanceId: string | null;
+  params: Record<string, unknown>;
+  routePath: string;
+  routeUrl: string;
+  pageStyle: Record<string, unknown>;
+};
+
+export type NebulaNativeModuleType = TurboModule & {
+  openMiniApp: (
+    appId: string,
+    initialProps: Record<string, unknown>,
+  ) => Promise<MiniAppResult>;
+  openMiniAppWithBundleURL: (
+    appId: string,
+    bundleURL: string,
+    connectToURLMetroServer: boolean,
+    initialProps: Record<string, unknown>,
+  ) => Promise<MiniAppResult>;
+  preloadMiniApp: (appId: string) => Promise<MiniAppResult>;
+  preloadMiniAppWithBundleURL: (
+    appId: string,
+    bundleURL: string,
+    connectToURLMetroServer: boolean,
+  ) => Promise<MiniAppResult>;
+  installMiniApp: (appId: string, bundleURL: string) => Promise<MiniAppResult>;
+  installMiniAppWithBundleURL: (
+    appId: string,
+    bundleURL: string,
+    connectToURLMetroServer: boolean,
+  ) => Promise<MiniAppResult>;
+  installMiniAppFromURLs: (
+    appId: string,
+    bundleURL: string,
+    manifestURL: string,
+    assetsURL: string,
+    connectToURLMetroServer: boolean,
+  ) => Promise<MiniAppResult>;
+  closeMiniApp: (appId: string) => Promise<MiniAppResult>;
+  uninstallMiniApp: (appId: string) => Promise<MiniAppResult>;
+  getCapabilities: () => Promise<{
+    bridgeVersion: string;
+    capabilities: Record<string, string>;
+  }>;
+  getServerBaseURL: () => Promise<ServerBaseURLResult>;
+  setServerBaseURL: (
+    serverBaseURL?: string | null,
+  ) => Promise<ServerBaseURLResult>;
+  setMiniappLoadingDelay: (
+    delayMs?: number | null,
+  ) => Promise<MiniappLoadingDelayResult>;
+  setMiniappLoadingEnterContentDelay: (
+    delayMs?: number | null,
+  ) => Promise<MiniappLoadingDelayResult>;
+  registerRoutes: (
+    appId: string,
+    routes: Record<string, string>,
+  ) => Promise<{ success: boolean; appId: string; count: number }>;
+  registerManifest: (
+    appId: string,
+    manifest: RegisteredMiniAppManifest,
+  ) => Promise<{ success: boolean; appId: string; count: number }>;
+  postMessageToHost: (
+    appId: string,
+    message: Record<string, unknown>,
+  ) => Promise<NavigationResult>;
+  postMessageToMiniApp: (
+    appId: string,
+    message: Record<string, unknown>,
+  ) => Promise<NavigationResult>;
+  bringHostToFront: () => Promise<HostVisibilityResult>;
+  restoreMiniApp: (token?: string | null) => Promise<HostVisibilityResult>;
+  presentHostModal: (
+    moduleName: string,
+    props: Record<string, unknown>,
+  ) => Promise<NavigationResult>;
+  dismissHostModal: () => Promise<NavigationResult>;
+  getInstalledMiniApps: () => Promise<InstalledMiniAppsResult>;
+  getInstalledMiniAppInfo: (
+    appId: string,
+  ) => Promise<InstalledMiniAppInfoResult>;
+  navigateTo: (appId: string, url: string) => Promise<NavigationResult>;
+  redirectTo: (appId: string, url: string) => Promise<NavigationResult>;
+  reLaunch: (appId: string, url: string) => Promise<NavigationResult>;
+  navigateBack: (appId: string, delta: number) => Promise<NavigationResult>;
+  setPageStyle: (
+    appId: string,
+    style: NebulaPageStyle,
+  ) => Promise<NavigationResult>;
+  showToast: (title: string) => Promise<NavigationResult>;
+  getDeviceInfo: () => Record<string, unknown>;
+};

package/src/pageConfig.ts

@@ -0,0 +1,13 @@
+export type MiniAppPageConfig = {
+  route?: string;
+  backgroundColor?: string;
+  navigationBarBackgroundColor?: string;
+  navigationBarTextColor?: string;
+  navigationBarTitleText?: string;
+  navigationStyle?: 'default' | 'custom';
+  visualEffectInBackground?: 'blur' | 'none';
+};
+
+export function definePageConfig<T extends MiniAppPageConfig>(config: T): T {
+  return config;
+}

package/src/specs/NativeNebulaModule.ts

@@ -0,0 +1,140 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+import type { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
+
+export type MiniAppUpdateStrategy = 'auto' | 'manual';
+
+export type MiniAppResult = {
+  success: boolean;
+  appId: string;
+  mode?: string;
+};
+
+export type InstalledMiniAppsResult = {
+  apps: string[];
+};
+
+export type InstalledMiniAppInfo = {
+  appId: string;
+  mode?: string | null;
+  bundlePath?: string | null;
+  sourceUrl?: string | null;
+  version?: string | null;
+  updateStrategy?: MiniAppUpdateStrategy | null;
+};
+
+export type InstalledMiniAppInfoResult = {
+  installed: boolean;
+  app?: InstalledMiniAppInfo | null;
+};
+
+export type ServerBaseURLResult = {
+  serverBaseURL?: string | null;
+};
+
+export type MiniappLoadingDelayResult = {
+  delayMs: number;
+};
+
+export type NebulaCapabilityMap = {
+  [capabilityName: string]: string;
+};
+
+export type NebulaCapabilitiesResult = {
+  bridgeVersion: string;
+  capabilities: NebulaCapabilityMap;
+};
+
+export type NavigationResult = {
+  errMsg: string;
+};
+
+export type HostVisibilityResult = {
+  success: boolean;
+  token?: string | null;
+};
+
+export type NebulaPageStyle = {
+  backgroundColor?: string;
+  navigationBarBackgroundColor?: string;
+  navigationBarTextColor?: string;
+  navigationBarTitleText?: string;
+  navigationStyle?: 'default' | 'custom';
+  visualEffectInBackground?: 'blur' | 'none';
+};
+
+export interface Spec extends TurboModule {
+  openMiniApp(
+    appId: string,
+    initialProps: UnsafeObject,
+  ): Promise<MiniAppResult>;
+  openMiniAppWithBundleURL(
+    appId: string,
+    bundleURL: string,
+    connectToURLMetroServer: boolean,
+    initialProps: UnsafeObject,
+  ): Promise<MiniAppResult>;
+  preloadMiniApp(appId: string): Promise<MiniAppResult>;
+  preloadMiniAppWithBundleURL(
+    appId: string,
+    bundleURL: string,
+    connectToURLMetroServer: boolean,
+  ): Promise<MiniAppResult>;
+  installMiniApp(appId: string, bundleURL: string): Promise<MiniAppResult>;
+  installMiniAppWithBundleURL(
+    appId: string,
+    bundleURL: string,
+    connectToURLMetroServer: boolean,
+  ): Promise<MiniAppResult>;
+  installMiniAppFromURLs(
+    appId: string,
+    bundleURL: string,
+    manifestURL: string,
+    assetsURL: string,
+    connectToURLMetroServer: boolean,
+  ): Promise<MiniAppResult>;
+  closeMiniApp(appId: string): Promise<MiniAppResult>;
+  uninstallMiniApp(appId: string): Promise<MiniAppResult>;
+  getCapabilities(): Promise<NebulaCapabilitiesResult>;
+  getServerBaseURL(): Promise<ServerBaseURLResult>;
+  setServerBaseURL(serverBaseURL?: string | null): Promise<ServerBaseURLResult>;
+  setMiniappLoadingDelay(
+    delayMs?: number | null,
+  ): Promise<MiniappLoadingDelayResult>;
+  setMiniappLoadingEnterContentDelay(
+    delayMs?: number | null,
+  ): Promise<MiniappLoadingDelayResult>;
+  getInstalledMiniApps(): Promise<InstalledMiniAppsResult>;
+  getInstalledMiniAppInfo(appId: string): Promise<InstalledMiniAppInfoResult>;
+  registerRoutes(appId: string, routes: UnsafeObject): Promise<UnsafeObject>;
+  registerManifest(
+    appId: string,
+    manifest: UnsafeObject,
+  ): Promise<UnsafeObject>;
+  postMessageToHost(
+    appId: string,
+    message: UnsafeObject,
+  ): Promise<NavigationResult>;
+  postMessageToMiniApp(
+    appId: string,
+    message: UnsafeObject,
+  ): Promise<NavigationResult>;
+  bringHostToFront(): Promise<HostVisibilityResult>;
+  restoreMiniApp(token?: string | null): Promise<HostVisibilityResult>;
+  presentHostModal(
+    moduleName: string,
+    props: UnsafeObject,
+  ): Promise<NavigationResult>;
+  dismissHostModal(): Promise<NavigationResult>;
+
+  // Mini-app navigation APIs
+  navigateTo(appId: string, url: string): Promise<NavigationResult>;
+  redirectTo(appId: string, url: string): Promise<NavigationResult>;
+  reLaunch(appId: string, url: string): Promise<NavigationResult>;
+  navigateBack(appId: string, delta: number): Promise<NavigationResult>;
+  setPageStyle(appId: string, style: UnsafeObject): Promise<NavigationResult>;
+  showToast(title: string): Promise<NavigationResult>;
+  getDeviceInfo(): UnsafeObject;
+}
+
+export default TurboModuleRegistry.get<Spec>('NebulaNativeModule');