@nebula-rn/sdk 0.0.1

package/src/hostApi.tsx

@@ -0,0 +1,364 @@
+import React from 'react';
+import { AppRegistry } from 'react-native';
+import { NebulaAPI } from './NebulaAPI';
+import type {
+  NebulaApiInvokeResult,
+  NebulaHostApiDescription,
+  NebulaHostApiHandler,
+} from './NebulaAPI';
+
+export function createHostApiFailure(
+  code: string,
+  message: string,
+): NebulaApiInvokeResult {
+  return {
+    ok: false,
+    error: {
+      code,
+      message,
+    },
+  };
+}
+
+export function createHostApiSuccess<TData>(
+  data: TData,
+): NebulaApiInvokeResult<TData> {
+  return {
+    ok: true,
+    data,
+  };
+}
+
+type PendingRequest<TRequest extends object> = TRequest & {
+  resolve: (result: NebulaApiInvokeResult) => void;
+};
+
+type Listener<TRequest extends object> = (request: TRequest | null) => void;
+
+export type HostModalChannel<TRequest extends object> = {
+  clear: () => void;
+  getCurrent: () => TRequest | null;
+  open: (request: TRequest) => Promise<NebulaApiInvokeResult>;
+  settle: (result: NebulaApiInvokeResult) => void;
+  subscribe: (listener: Listener<TRequest>) => () => void;
+};
+
+export type NebulaHostFeature = {
+  name: string;
+  description?: NebulaHostApiDescription;
+  register: () => void | (() => void);
+};
+
+export function createHostModalChannel<
+  TRequest extends object,
+>(): HostModalChannel<TRequest> {
+  let pendingRequest: PendingRequest<TRequest> | null = null;
+  const listeners = new Set<Listener<TRequest>>();
+
+  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);
+      };
+    },
+  };
+}
+
+type HostModalApiOptions<TPayload extends object, TRequest extends object> = {
+  apiName: string;
+  description?: NebulaHostApiDescription;
+  component: React.ComponentType<any>;
+  channel: HostModalChannel<TRequest>;
+  createRequest: (payload: TPayload) => TRequest;
+  modalProps?:
+    | Record<string, unknown>
+    | ((payload: TPayload, request: TRequest) => Record<string, unknown>);
+  onBeforeOpen?: (
+    payload: TPayload,
+  ) => Promise<NebulaApiInvokeResult | null | void>;
+  onUnmountErrorMessage?: string;
+  version?: string;
+};
+
+export type RegisterHostModalApiOptions<
+  TPayload extends object,
+  TRequest extends object,
+> = HostModalApiOptions<TPayload, TRequest>;
+
+export type RegisterHostApiOptions = {
+  apiName: string;
+  supported?: NebulaHostApiHandler['supported'];
+  version?: string;
+  description?: NebulaHostApiDescription;
+  handle: NebulaHostApiHandler['handle'];
+};
+
+export type CreateMockHostApiOptions = {
+  apiName: string;
+  version?: string;
+  description?: NebulaHostApiDescription;
+  delayMs?: number;
+  result?:
+    | unknown
+    | ((payload: Record<string, unknown>) => unknown | Promise<unknown>);
+  error?:
+    | {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+      }
+    | ((payload: Record<string, unknown>) =>
+        | {
+            code: string;
+            message: string;
+            details?: Record<string, unknown>;
+          }
+        | Promise<{
+            code: string;
+            message: string;
+            details?: Record<string, unknown>;
+          }>);
+};
+
+function getHostModalModuleName(apiName: string): string {
+  const normalizedName = apiName.replace(/[^a-zA-Z0-9_]+/g, '_');
+  return `NebulaHostModal_${normalizedName}`;
+}
+
+function createHostModalApiHandler<
+  TPayload extends object,
+  TRequest extends object,
+>({
+  apiName,
+  channel,
+  createRequest,
+  modalProps,
+  onBeforeOpen,
+  version = '1.0',
+  description,
+}: Omit<HostModalApiOptions<TPayload, TRequest>, 'component'>) {
+  const modalModuleName = getHostModalModuleName(apiName);
+  let requestInFlight = false;
+
+  return {
+    version,
+    description,
+    handle: async (payload: Record<string, unknown>) => {
+      if (requestInFlight) {
+        return createHostApiFailure(
+          'SCAN_FAILED',
+          `${apiName}:fail another request is already in progress`,
+        );
+      }
+
+      const typedPayload = payload as TPayload;
+      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<
+  TPayload extends object,
+  TRequest extends object,
+>({
+  apiName,
+  component,
+  channel,
+  createRequest,
+  modalProps,
+  onBeforeOpen,
+  onUnmountErrorMessage,
+  version = '1.0',
+  description,
+}: RegisterHostModalApiOptions<TPayload, TRequest>): () => void {
+  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,
+}: RegisterHostApiOptions): NebulaHostFeature {
+  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,
+}: CreateMockHostApiOptions): NebulaHostFeature {
+  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<
+  TPayload extends object,
+  TRequest extends object,
+>(options: RegisterHostModalApiOptions<TPayload, TRequest>): NebulaHostFeature {
+  return {
+    name: options.apiName,
+    description: options.description,
+    register() {
+      return registerHostModalApi(options);
+    },
+  };
+}
+
+export function createHostModalApiBridge<
+  TPayload extends object,
+  TRequest extends object,
+>(options: HostModalApiOptions<TPayload, TRequest>) {
+  return function HostModalApiBridge(): React.ReactElement | null {
+    React.useEffect(() => registerHostModalApi(options), []);
+
+    return null;
+  };
+}
+
+export function registerHostModalComponent<P extends object>(
+  moduleName: string,
+  component: React.ComponentType<P>,
+): string {
+  AppRegistry.registerComponent(moduleName, () => component);
+  return moduleName;
+}

package/src/hostProtocol.ts

@@ -0,0 +1,209 @@
+import type {
+  NebulaHostApiDescriptionMap,
+  NebulaHostApiHandler,
+  NebulaHostCapabilityMap,
+  NebulaProtocolResponse,
+} from './nebulaTypes';
+import {
+  addNebulaEventListener,
+  isProtocolRequest,
+  NEBULA_HOST_MESSAGE_EVENT,
+} from './nebulaNative';
+
+const hostApiRegistry = new Map<string, NebulaHostApiHandler>();
+let hostApiServerStarted = false;
+let hostApiServerUnsubscribe: (() => void) | null = null;
+
+export async function resolveHostCapabilities(): Promise<NebulaHostCapabilityMap> {
+  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,
+        },
+      ] as const;
+    }),
+  );
+
+  return entries.reduce<NebulaHostCapabilityMap>((capabilities, entry) => {
+    capabilities[entry[0]] = entry[1];
+    return capabilities;
+  }, {});
+}
+
+export function resolveHostApiDescriptions(): NebulaHostApiDescriptionMap {
+  return Array.from(
+    hostApiRegistry.entries(),
+  ).reduce<NebulaHostApiDescriptionMap>((descriptions, [apiName, handler]) => {
+    if (handler.description) {
+      descriptions[apiName] = handler.description;
+    }
+    return descriptions;
+  }, {});
+}
+
+export function startHostApiServer(
+  postMessageToMiniApp: (
+    appId: string,
+    message: NebulaProtocolResponse,
+  ) => Promise<{ errMsg: string }>,
+): void {
+  if (hostApiServerStarted) {
+    return;
+  }
+
+  const unsubscribe = addNebulaEventListener(
+    NEBULA_HOST_MESSAGE_EVENT,
+    event => {
+      const message = event.message;
+      if (!isProtocolRequest(message)) {
+        return;
+      }
+
+      const reply = async (response: NebulaProtocolResponse) => {
+        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(): void {
+  hostApiServerUnsubscribe?.();
+  hostApiServerUnsubscribe = null;
+  hostApiServerStarted = false;
+}
+
+export function registerHostApiHandler(
+  apiName: string,
+  handler: NebulaHostApiHandler,
+): void {
+  hostApiRegistry.set(apiName, handler);
+}
+
+export function unregisterHostApiHandler(apiName: string): void {
+  hostApiRegistry.delete(apiName);
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+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';