react-native-acoustic-connect-beta 18.0.25 → 18.0.27

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

@@ -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>
 }