react-native-acoustic-connect-beta 18.0.26 → 18.0.28

package/src/TLTRN.ts

@@ -16,13 +16,29 @@ import DialogListener from "./utils/DialogListener";
 import type { DialogEvent, DialogButtonClickEvent, DialogDismissEvent } from "./utils/DialogListener";
 import AcousticConnectRN from './index'; 
 
+// Preserve any previously-installed handler (e.g. React Native's red-box
+// handler) so we augment rather than replace it.
 // @ts-ignore
-global.ErrorUtils.setGlobalHandler((e: any, _isFatal: boolean) => {
-  AcousticConnectRN.logExceptionEvent(
-      JSON.stringify(e),
-      JSON.stringify(e),
-      true
-  );
+const previousGlobalErrorHandler = global.ErrorUtils?.getGlobalHandler?.();
+
+// @ts-ignore
+global.ErrorUtils?.setGlobalHandler?.((e: any, isFatal: boolean) => {
+  // A global error handler must never throw — otherwise it masks the ORIGINAL
+  // error. `AcousticConnectRN` can be undefined here (e.g. the native module
+  // failed to load, or during the module-load circular import), so guard the
+  // call and always forward to the previous handler so the real error still
+  // surfaces and fatals still crash.
+  try {
+    AcousticConnectRN?.logExceptionEvent?.(
+        JSON.stringify(e),
+        JSON.stringify(e),
+        true
+    );
+  } catch (loggingError: Error | any) {
+    console.warn('TLTRN: failed to log uncaught exception:', loggingError?.message);
+  } finally {
+    previousGlobalErrorHandler?.(e, isFatal);
+  }
 });
 
 class TLTRN {
@@ -294,11 +310,15 @@ class TLTRN {
     }
 
     if (message.module === "ExceptionsManager") {
-      AcousticConnectRN.logExceptionEvent(
-        message.args[0],
-        JSON.stringify(message.args[1]),
-        true
-      );
+      try {
+        AcousticConnectRN?.logExceptionEvent?.(
+          message.args[0],
+          JSON.stringify(message.args[1]),
+          true
+        );
+      } catch (error: Error | any) {
+        console.log('logExceptionEvent (bridge) error: ', error?.message);
+      }
     }
   };
 

package/src/components/Connect.tsx

@@ -37,7 +37,7 @@ const Connect: React.FC<ConnectProps> = ({
     navigationRef,
 }) => {
     const child = children as any;
-    // CA-138631: React 19 moved the ref off `element.ref` onto `element.props.ref`.
+    // React 19 moved the ref off `element.ref` onto `element.props.ref`.
     // Read `props.ref` first; the legacy `child.ref` fallback is a defensive
     // guard from the React 18 era — kept to avoid a behavioural change.
     const childProvidedRef = child?.props?.ref ?? child?.ref;

package/src/index.ts

@@ -7,7 +7,7 @@
 * Acoustic, L.P. Any unauthorized copying or distribution of content from this file is
 * prohibited.
 * 
-* Created by Omar Hernandez on 5/9/25.
+* Created on 5/9/25.
 * 
 ********************************************************************************************/
 
@@ -21,7 +21,24 @@ import { withAcousticAutoDialog } from './utils/withAcousticAutoDialog'
 import DialogDebugger from './utils/DialogDebugger'
 import TLTRN from './TLTRN'
 
-const AcousticConnectRN = NitroModules.createHybridObject<AcousticConnectRNSpec>('AcousticConnectRN')
+// Instantiating the native HybridObject is the first thing that fails when the
+// app's `react-native-nitro-modules` runtime does not match the version this SDK
+// was generated against (the generated registration is tightly coupled to the
+// Nitro version — see peerDependencies). Without this guard the failure surfaces
+// as an opaque `ClassNotFoundException` and an `undefined` module far from the
+// cause. Re-throw with an actionable message instead.
+let AcousticConnectRN: AcousticConnectRNSpec
+try {
+  AcousticConnectRN = NitroModules.createHybridObject<AcousticConnectRNSpec>('AcousticConnectRN')
+} catch (error) {
+  throw new Error(
+    '[AcousticConnectRN] Failed to load the native HybridObject. This almost ' +
+      'always means a `react-native-nitro-modules` version mismatch: this SDK is ' +
+      'built against the exact version declared in its peerDependencies, so your ' +
+      'app must resolve that same version (check `npm ls react-native-nitro-modules`). ' +
+      `Original error: ${String(error)}`
+  )
+}
 
 export { Connect, TLTRN, KeyboardListener, DialogListener, useDialogTracking, DialogDebugger, withAcousticAutoDialog }
 export default AcousticConnectRN

package/src/specs/react-native-acoustic-connect.nitro.ts

@@ -7,7 +7,7 @@
 // prohibited.
 //
 //
-//  Created by Omar Hernandez on 5/9/25.
+//  Created on 5/9/25.
 //
 
 import { type HybridObject } from 'react-native-nitro-modules'
@@ -20,6 +20,38 @@ export type KeyValueObject = {
 
 export type ConnectMonitoringLevelType = 'Ignore' | 'CellularAndWiFi' | 'WiFi'
 
+/**
+ * Structured error describing an APNs / permission failure.
+ *
+ * Mirrors the `firebase-messaging` / `notifee` ecosystem convention so callers
+ * can forward a native error object without string-encoding it. The native
+ * bridge reconstructs an `NSError` (iOS) from these fields.
+ */
+export interface PushErrorInfo {
+    /** Platform error code, when available (maps to `NSError.code`). */
+    code?: number
+    /** Platform error domain, when available (maps to `NSError.domain`). */
+    domain?: string
+    /** Human-readable failure description (maps to `NSLocalizedDescriptionKey`). */
+    message: string
+}
+
+/**
+ * Result of a permission request.
+ *
+ * The Promise from {@link AcousticConnectRN.pushRequestPermission} always
+ * resolves with this shape and never rejects. `error` is `null` on success or
+ * a denial with no system error; a non-null string carries the system error's
+ * localized description, or `'permission-prompt-abandoned'` if the host was
+ * destroyed mid-prompt.
+ */
+export interface PushPermissionResult {
+    /** `true` if the user granted permission, `false` otherwise. */
+    granted: boolean
+    /** `null` on success/clean denial; otherwise a description of the error. */
+    error?: string | null
+}
+
 export interface AcousticConnectRN extends HybridObject<{ ios: 'swift', android: 'kotlin' }> {
     /**
      * Re-enables the Connect SDK after a prior {@link disable} call.
@@ -107,4 +139,100 @@ export interface AcousticConnectRN extends HybridObject<{ ios: 'swift', android:
     logDialogDismissEvent(dialogId: string, dismissReason: string): boolean
     logDialogButtonClickEvent(dialogId: string, buttonText: string, buttonIndex: number): boolean
     logDialogCustomEvent(dialogId: string, eventName: string, values: Record<string, string | number | boolean>): boolean
+
+    // ── Push: APNs lifecycle (iOS) ──────────────────────────────────────────
+    //
+    // Push mode (automatic / manual / off) is configured in `ConnectConfig.json`
+    // and enforced by the native SDK — there is no JS-side mode argument. In
+    // automatic mode the SDK's swizzled delegate handles everything and these
+    // forwarding calls are redundant-but-safe; in manual mode they are the only
+    // path for events to reach the SDK.
+
+    /**
+     * Forwards the raw APNs device token to the Connect SDK (manual mode).
+     *
+     * Nitro maps `ArrayBuffer` ↔ `Data` natively; the bridge forwards the bytes
+     * unchanged with no hex conversion and no validation.
+     *
+     * @param deviceToken Raw APNs device-token bytes from
+     *   `didRegisterForRemoteNotificationsWithDeviceToken`.
+     * @returns A promise resolving to `true` once the SDK accepted the token,
+     *   or `false` if the SDK rejected the call (e.g. push not enabled). Never
+     *   rejects.
+     */
+    pushDidRegisterWithToken(deviceToken: ArrayBuffer): Promise<boolean>
+
+    /**
+     * Forwards an APNs registration failure to the Connect SDK (manual mode).
+     *
+     * @param error Structured error; the bridge builds an `NSError` from it.
+     * @returns A promise resolving to `true` once forwarded, `false` on failure.
+     *   Never rejects.
+     */
+    pushDidFailToRegister(error: PushErrorInfo): Promise<boolean>
+
+    /**
+     * Forwards a received notification to the Connect SDK so it can log a
+     * `pushReceived` signal (manual mode).
+     *
+     * The bridge branches on the push mode resolved from `ConnectConfig.json`:
+     * manual mode forwards to the SDK and returns `true`; automatic/off mode
+     * returns `false` (bridge error `EAC-RN-007`) without forwarding, because
+     * the SDK's own delegate already handles delivery in automatic mode and
+     * forwarding would double-log.
+     *
+     * @param userInfo The notification `userInfo` payload.
+     * @returns A promise resolving to `true` if processed (manual mode), or
+     *   `false` in automatic/off mode (`EAC-RN-007`). Never rejects.
+     */
+    pushDidReceiveNotification(userInfo: Record<string, string | number | boolean>): Promise<boolean>
+
+    /**
+     * Forwards a notification response (tap / action) to the Connect SDK so it
+     * can run the built-in action and log a `pushAction` signal (manual mode).
+     *
+     * Same `EAC-RN-007` (`false`) behaviour in automatic mode as
+     * {@link pushDidReceiveNotification}.
+     *
+     * @param actionIdentifier The response action identifier.
+     * @param userInfo The notification `userInfo` payload.
+     * @returns A promise resolving to `true` if processed (manual mode), or
+     *   `false` in automatic/off mode (`EAC-RN-007`). Never rejects.
+     */
+    pushDidReceiveResponse(actionIdentifier: string, userInfo: Record<string, string | number | boolean>): Promise<boolean>
+
+    // ── Push: permission management (cross-platform) ────────────────────────
+
+    /**
+     * Forwards externally-obtained permission state to the SDK.
+     *
+     * Tri-state `granted`: `true` granted, `false` denied, `null` not yet
+     * determined. For `null` the bridge records the state but does not call the
+     * SDK (it has no notion of forwarding "unknown").
+     *
+     * @param granted Tri-state permission value.
+     * @param error Optional structured error accompanying a denial.
+     * @returns A promise resolving to `true` once handled — including the
+     *   `null`/not-determined case, which is intentionally accepted without
+     *   forwarding to the SDK. `false` only if the SDK rejected a forwarded
+     *   state. Never rejects.
+     */
+    pushDidReceiveAuthorization(granted: boolean | null, error?: PushErrorInfo): Promise<boolean>
+
+    /**
+     * Requests notification permission via the SDK, presenting the system prompt
+     * when undetermined.
+     *
+     * Always resolves, never rejects — see {@link PushPermissionResult}.
+     *
+     * @returns The permission result.
+     */
+    pushRequestPermission(): Promise<PushPermissionResult>
+
+    /**
+     * Reads the current notification permission state without prompting.
+     *
+     * @returns Tri-state: `true` granted, `false` denied, `null` not determined.
+     */
+    pushGetPermissionState(): Promise<boolean | null>
 }

package/src/utils/withAcousticAutoDialog.tsx

@@ -7,7 +7,7 @@
 * Acoustic, L.P. Any unauthorized copying or distribution of content from this file is
 * prohibited.
 * 
-* Created by Omar Hernandez on 5/9/25.
+* Created on 5/9/25.
 * 
 ********************************************************************************************/