@icedevml/react-native-host-card-emulation 0.9.2 → 1.0.0

package/js/session.ts

@@ -0,0 +1,192 @@
+import NativeHCEModule, {NativeHCEEvent} from './NativeHCEModule';
+import {
+  addSessionListener,
+  callHandler,
+  HCEError,
+  processApdu,
+  reportError,
+  resolveHandlerOptions,
+  SerialQueue,
+} from './internal';
+import type {BeginSessionOptions, EmulationStopStatus, HCESession, SessionHandlers} from './types';
+
+let sessionCounter = 0;
+
+function generateSessionId(): string {
+  sessionCounter += 1;
+  return `fg-${Date.now().toString(36)}-${sessionCounter.toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+class Session implements HCESession {
+  readonly id: string;
+  readonly closed: Promise<string>;
+  readonly started: Promise<void>;
+
+  private readonly handlers: SessionHandlers;
+  private readonly handlerTimeout: number;
+  private readonly queue = new SerialQueue();
+  private readonly removeListener: () => void;
+  private active = true;
+  private isStarted = false;
+  private resolveClosed!: (reason: string) => void;
+  private resolveStarted!: () => void;
+  private rejectStarted!: (error: Error) => void;
+
+  constructor(id: string, handlers: SessionHandlers, handlerTimeout: number) {
+    this.id = id;
+    this.handlers = handlers;
+    this.handlerTimeout = handlerTimeout;
+    this.closed = new Promise(resolve => {
+      this.resolveClosed = resolve;
+    });
+    this.started = new Promise((resolve, reject) => {
+      this.resolveStarted = resolve;
+      this.rejectStarted = reject;
+    });
+    // beginSession() handles the rejection, avoid unhandled rejection warnings when it doesn't wait for it
+    this.started.catch(() => {});
+    // registered before the native session is created, so that no event can be missed
+    this.removeListener = addSessionListener(id, event => this.handleEvent(event));
+  }
+
+  get isActive(): boolean {
+    return this.active;
+  }
+
+  private runHandler(name: string, handler: (() => unknown) | undefined) {
+    if (!handler) {
+      return;
+    }
+
+    this.queue
+      .push(() => callHandler(name, handler, this.handlerTimeout))
+      .catch(e => reportError(this.handlers.onError, e));
+  }
+
+  private handleEvent(event: NativeHCEEvent) {
+    switch (event.type) {
+      case 'sessionStarted':
+        this.isStarted = true;
+        this.resolveStarted();
+        break;
+
+      case 'readerDetected':
+        this.runHandler('onReaderDetected()', this.handlers.onReaderDetected);
+        break;
+
+      case 'readerLost':
+        this.runHandler('onReaderLost()', this.handlers.onReaderLost);
+        break;
+
+      case 'apdu':
+        this.queue.push(() =>
+          processApdu(this.id, event, this.handlers.onApdu, this.handlers.onError, this.handlerTimeout),
+        );
+        break;
+
+      case 'sessionInvalidated':
+        this.close(event.reason || 'unknown');
+        break;
+    }
+  }
+
+  close(reason: string) {
+    if (!this.active) {
+      return;
+    }
+
+    this.active = false;
+    this.removeListener();
+
+    if (!this.isStarted) {
+      // beginSession() rejects, so the app never gets the session object and isn't notified
+      this.rejectStarted(new HCEError('err_session_invalidated', `The session was invalidated: ${reason}`));
+    } else {
+      const onInvalidated = this.handlers.onInvalidated;
+      this.runHandler('onInvalidated()', onInvalidated ? () => onInvalidated(reason) : undefined);
+    }
+
+    this.resolveClosed(reason);
+  }
+
+  private ensureActive() {
+    if (!this.active) {
+      throw new HCEError('err_no_session', 'The session is not active.');
+    }
+  }
+
+  async startEmulation(): Promise<void> {
+    this.ensureActive();
+    await NativeHCEModule.startEmulation(this.id);
+  }
+
+  async stopEmulation(status: EmulationStopStatus = 'success'): Promise<void> {
+    this.ensureActive();
+    await NativeHCEModule.stopEmulation(this.id, status);
+  }
+
+  async isEmulationRunning(): Promise<boolean> {
+    if (!this.active) {
+      return false;
+    }
+
+    return NativeHCEModule.isEmulationRunning(this.id);
+  }
+
+  setAlertMessage(message: string): void {
+    if (this.active) {
+      NativeHCEModule.setSessionAlertMessage(this.id, message);
+    }
+  }
+
+  invalidate(): void {
+    if (!this.active) {
+      return;
+    }
+
+    NativeHCEModule.invalidateSession(this.id);
+    // don't rely on the native event, the session is closed from now on
+    this.close('userInvalidated');
+  }
+}
+
+/**
+ * Begin the HCE session. Resolves once the session is started and ready for startEmulation().
+ * Only a single session can be active at a time.
+ */
+export async function beginSession(handlers: SessionHandlers, options: BeginSessionOptions = {}): Promise<HCESession> {
+  if (!handlers || typeof handlers.onApdu !== 'function') {
+    throw new HCEError('err_invalid_argument', 'handlers.onApdu must be a function.');
+  }
+
+  const {signal} = options;
+  const {handlerTimeout, allowWhenLocked} = resolveHandlerOptions(options);
+
+  if (signal?.aborted) {
+    throw new HCEError('err_aborted', 'The operation was aborted.');
+  }
+
+  const session = new Session(generateSessionId(), handlers, handlerTimeout);
+  const onAbort = () => session.invalidate();
+  signal?.addEventListener('abort', onAbort);
+  session.closed.then(() => signal?.removeEventListener('abort', onAbort));
+
+  try {
+    await NativeHCEModule.beginSession(session.id, allowWhenLocked);
+  } catch (e) {
+    session.close('beginSessionFailed');
+    throw e;
+  }
+
+  try {
+    await session.started;
+  } catch (e) {
+    if (signal?.aborted) {
+      throw new HCEError('err_aborted', 'The operation was aborted.');
+    }
+
+    throw e;
+  }
+
+  return session;
+}

package/js/types.ts

@@ -0,0 +1,179 @@
+export type HCEPlatform = 'android' | 'ios';
+
+export interface HCECapabilities {
+  readonly platform: HCEPlatform;
+  /**
+   * Whether the device and the OS version support host card emulation at all.
+   */
+  readonly hceSupported: boolean;
+  /**
+   * Whether NFC is currently enabled (Android) / available for reading (iOS).
+   */
+  readonly nfcEnabled: boolean;
+  /**
+   * Whether the app is allowed to use HCE right now.
+   * iOS: result of CardSession.isEligible (region, entitlement, etc.).
+   * Android: same as hceSupported.
+   */
+  readonly eligible: boolean;
+  /**
+   * Whether registerBackgroundHandler() is supported (Android only).
+   */
+  readonly backgroundSupported: boolean;
+  /**
+   * Whether acquireExclusiveNFC() is supported (iOS only).
+   */
+  readonly presentmentSupported: boolean;
+}
+
+export interface CommandAPDU {
+  /**
+   * Identifier of the C-APDU, unique within the app process.
+   */
+  readonly id: number;
+  /**
+   * Raw bytes of the C-APDU.
+   */
+  readonly command: Uint8Array;
+  /**
+   * Whether the device was locked when the C-APDU was received.
+   * iOS: always false, it's impossible to communicate over HCE while the device is locked.
+   */
+  readonly deviceLocked: boolean;
+}
+
+/**
+ * Raw bytes of the R-APDU, including the status word (at least 2 bytes).
+ */
+export type ResponseAPDU = Uint8Array | ReadonlyArray<number>;
+
+export type ApduHandler = (apdu: CommandAPDU) => ResponseAPDU | Promise<ResponseAPDU>;
+
+export type EmulationStopStatus = 'success' | 'failure';
+
+export interface SessionHandlers {
+  /**
+   * Handle the C-APDU and return the R-APDU. Called sequentially, the next C-APDU is never
+   * delivered before the previous call has finished. If the handler throws, returns an invalid
+   * response or doesn't finish within the handler timeout, the reader receives the 6F00 status word
+   * (no precise diagnosis).
+   */
+  onApdu: ApduHandler;
+  /**
+   * iOS: The reader's field was detected.
+   * Android: The reader has selected the application.
+   */
+  onReaderDetected?: () => void | Promise<void>;
+  /**
+   * The reader was lost, a different application was selected by the reader or the emulation was stopped.
+   */
+  onReaderLost?: () => void | Promise<void>;
+  /**
+   * The session was closed and can't be used anymore.
+   */
+  onInvalidated?: (reason: string) => void;
+  /**
+   * Errors thrown by the handlers above (including the err_handler_timeout errors)
+   * or by responding to a C-APDU. Logged with console.warn() if not provided.
+   */
+  onError?: (error: unknown) => void;
+}
+
+export interface HandlerOptions {
+  /**
+   * The maximum time (in milliseconds) a single handler call may take, including the returned promise.
+   * Once it's exceeded, the handler's result is ignored, onError() receives an err_handler_timeout error
+   * and the next event is delivered (a timed out onApdu() is responded to with the 6F00 status word).
+   * Without the limit, a handler that never finishes would block all the subsequent events.
+   *
+   * Default: 10000. Pass 0 or Infinity to disable the timeout.
+   */
+  handlerTimeout?: number;
+  /**
+   * Android: Whether the interaction is allowed while the device is locked. If false, the C-APDUs
+   * received while the device is locked are never delivered to the handlers and the reader receives
+   * an error status word instead. Set it to false unless the app is meant to work on the lock screen.
+   * iOS: Ignored, it's impossible to communicate over HCE while the device is locked.
+   *
+   * Default: true.
+   */
+  allowWhenLocked?: boolean;
+}
+
+export interface BeginSessionOptions extends HandlerOptions {
+  /**
+   * Aborting the signal invalidates the session, also if it's still being started.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * The options of the background handler, handlerTimeout also applies to the factory.
+ */
+export type BackgroundHandlerOptions = HandlerOptions;
+
+export interface HCESession {
+  readonly id: string;
+  /**
+   * Whether the session is still open.
+   */
+  readonly isActive: boolean;
+  /**
+   * Resolves with the reason once the session is closed.
+   */
+  readonly closed: Promise<string>;
+
+  /**
+   * iOS: Start the card emulation, displaying the system NFC UI.
+   * Android: Start forwarding C-APDUs to this session.
+   */
+  startEmulation(): Promise<void>;
+  /**
+   * iOS: Stop the card emulation with "success"/"failure" UI status.
+   * Android: Stop forwarding C-APDUs to this session (the status is ignored).
+   */
+  stopEmulation(status?: EmulationStopStatus): Promise<void>;
+  isEmulationRunning(): Promise<boolean>;
+  /**
+   * iOS: Set the alert message of the system NFC UI.
+   * Android: No-op.
+   */
+  setAlertMessage(message: string): void;
+  /**
+   * Close the session. Idempotent.
+   */
+  invalidate(): void;
+}
+
+/**
+ * - 'background': the app is not in foreground (or not running at all).
+ * - 'foreground': the app is in foreground, but it has no session with running emulation.
+ */
+export type BackgroundAppState = 'background' | 'foreground';
+
+export interface BackgroundContext {
+  readonly sessionId: string;
+  readonly appState: BackgroundAppState;
+}
+
+export interface BackgroundHandlers {
+  /**
+   * Same semantics as SessionHandlers.onApdu.
+   */
+  onApdu: ApduHandler;
+  /**
+   * The reader was lost or a different application was selected by the reader.
+   * The background interaction ends after this handler has finished.
+   */
+  onReaderLost?: () => void | Promise<void>;
+  onError?: (error: unknown) => void;
+}
+
+/**
+ * Called once per interaction with the reader, so the returned handlers can safely keep
+ * the state of that interaction in a closure. If it throws or doesn't finish within the handler
+ * timeout, the reader receives an error status word for the rest of the interaction.
+ */
+export type BackgroundHandlerFactory = (
+  context: BackgroundContext,
+) => BackgroundHandlers | Promise<BackgroundHandlers>;

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "@icedevml/react-native-host-card-emulation",
-  "version": "0.9.2",
+  "version": "1.0.0",
   "description": "Host Card Emulation (HCE) React Native Turbo Module for iOS and Android platforms.",
-  "react-native": "js/index",
-  "source": "js/index",
+  "main": "js/index.ts",
+  "types": "js/index.ts",
+  "react-native": "js/index.ts",
+  "source": "js/index.ts",
+  "scripts": {
+    "test": "jest"
+  },
   "files": [
     "js",
     "android",
     "ios",
     "RTNHCEModuleIOS.podspec",
+    "Package.swift",
+    "react-native-spm-prefix.h",
     "!android/build",
     "!ios/build",
     "!**/__tests__",
@@ -32,6 +39,15 @@
     "react": "*",
     "react-native": "*"
   },
+  "devDependencies": {
+    "@babel/core": "^7.25.2",
+    "@react-native/babel-preset": "0.88.1",
+    "@react-native/jest-preset": "0.88.1",
+    "@types/jest": "^29.5.13",
+    "jest": "^29.6.3",
+    "react": "19.3.0",
+    "react-native": "0.88.1"
+  },
   "codegenConfig": {
     "name": "RTNHCEModuleSpec",
     "type": "modules",

package/react-native-spm-prefix.h

@@ -0,0 +1,10 @@
+// AUTO-SCAFFOLDED by react-native spm scaffold — mirrors CocoaPods' default
+// prefix header so ObjC sources that rely on an implicit Foundation/UIKit
+// import compile under SPM (which has no prefix-header mechanism). Safe to
+// delete + regenerate via `npx react-native spm scaffold`.
+#ifdef __OBJC__
+#import <Foundation/Foundation.h>
+#if __has_include(<UIKit/UIKit.h>)
+#import <UIKit/UIKit.h>
+#endif
+#endif

package/android/src/main/AndroidMainfest.xml

@@ -1,3 +0,0 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-          package="com.itsecrnd.rtnhceandroid">
-</manifest>

package/android/src/main/java/com/itsecrnd/rtnhceandroid/HCEServiceCallback.java

@@ -1,7 +0,0 @@
-package com.itsecrnd.rtnhceandroid;
-
-public interface HCEServiceCallback {
-    void onBackgroundHCEInit(String handle);
-    void onBackgroundHCEFinish(String handle);
-    void onRespondAPDU(String handle, String rapdu);
-}

package/js/hceBackground.ts

@@ -1,68 +0,0 @@
-import NativeHCEModule, {HCEModuleBackgroundEvent} from "./NativeHCEModule";
-
-/**
- * Android: Data passed by the native side to the 'handleBackgroundHCECall' headless task.
- * Pass it as-is to createBackgroundHCE().
- */
-export interface BackgroundHCETaskData {
-    /**
-     * Handle of the background HCE session.
-     */
-    handle: string,
-}
-
-export interface BackgroundEventHandler {
-    (
-        event: HCEModuleBackgroundEvent,
-        respondAPDU: (rapdu: string) => Promise<void>,
-        taskData: BackgroundHCETaskData,
-    ): Promise<void>
-}
-
-export interface ProcessBackgroundHCEFunc {
-    (
-        handler: BackgroundEventHandler
-    ): void
-}
-
-/**
- * Set up handling of a background HCE session.
- *
- * @param taskData Data received by the 'handleBackgroundHCECall' headless task. A bare handle
- *                 string is accepted as well, for backwards compatibility.
- */
-export const createBackgroundHCE = (taskData: BackgroundHCETaskData | string): ProcessBackgroundHCEFunc => {
-    const useTaskData: BackgroundHCETaskData = typeof taskData === "string"
-        ? {handle: taskData}
-        : taskData;
-    const handle = useTaskData.handle;
-
-    const respondAPDU = (rapdu: string) => {
-        return NativeHCEModule.respondAPDU(handle, rapdu);
-    }
-
-    return (handler: BackgroundEventHandler) => {
-        const subscription = NativeHCEModule.onBackgroundEvent(async (event) => {
-            if (event.audience !== handle) {
-                // ignore
-                return;
-            }
-
-            try {
-                await handler(event, respondAPDU, useTaskData);
-            } catch (e) {
-                throw e;
-            } finally {
-                if (event.type === "readerDeselected") {
-                    subscription.remove();
-                    NativeHCEModule.finishBackgroundHCE(handle);
-                }
-            }
-        });
-
-        if (!NativeHCEModule.beginBackgroundHCE(handle)) {
-            subscription.remove();
-            NativeHCEModule.finishBackgroundHCE(handle);
-        }
-    }
-}