feat(android): add support for Firebase Phone Number Verification (PNV)

fix reviews

Author: just1and0

docs/phone-number-verification/usage/index.mdx

@@ -72,7 +72,7 @@ The method returns an array with one entry per SIM slot. Each entry includes:
 - `isSupported` — whether PNV is available for this SIM.
 - `simSlot` — the SIM slot index (0-based).
 - `carrierId` — the carrier identifier string.
-- `reason` — a `VerificationSupportStatus` string explaining why the SIM is or isn't supported.
+- `reason` — a {@link VerificationSupportStatus} string explaining why the SIM is or isn't supported.
 
 ### Query a specific SIM slot
 

packages/phone-number-verification/lib/modular.ts

@@ -18,19 +18,21 @@
 import { Platform } from 'react-native';
 import { getReactNativeModule } from '@react-native-firebase/app/dist/module/internal/nativeModule';
 
-import type { VerificationSupportInfo, VerifiedPhoneNumberResult } from './types/pnv';
+import type { VerificationSupportResult, VerifiedPhoneNumberTokenResult } from './types/pnv';
 
 const UNSUPPORTED_MSG = 'Firebase Phone Number Verification is only supported on Android.';
 
 const NATIVE_MODULE_NAME = 'RNFBPnvModule';
 
 interface NativePnvModule {
   enableTestSession(token: string): Promise<void>;
-  getVerificationSupportInfo(): Promise<VerificationSupportInfo[]>;
-  getVerificationSupportInfoForSimSlot(simSlot: number): Promise<VerificationSupportInfo[]>;
-  getVerifiedPhoneNumber(): Promise<VerifiedPhoneNumberResult>;
+  getVerificationSupportInfo(): Promise<VerificationSupportResult[]>;
+  getVerificationSupportInfoForSimSlot(simSlot: number): Promise<VerificationSupportResult[]>;
+  getVerifiedPhoneNumber(): Promise<VerifiedPhoneNumberTokenResult>;
   getDigitalCredentialPayload(nonce: string): Promise<string>;
-  exchangeCredentialResponseForPhoneNumber(dcApiResponse: string): Promise<VerifiedPhoneNumberResult>;
+  exchangeCredentialResponseForPhoneNumber(
+    dcApiResponse: string,
+  ): Promise<VerifiedPhoneNumberTokenResult>;
 }
 
 function getNativeModule(): NativePnvModule {
@@ -49,11 +51,17 @@ function getNativeModule(): NativePnvModule {
 /**
  * Enables a test session for SIM-less testing.
  * Must be called only once per app instance; subsequent calls will reject with
- * error code `test-session-already-enabled`.
+ * error code `pnv/test-session-already-enabled`.
  *
+ * @remarks
  * In test mode, phone numbers follow the format: valid country code followed by all zeros.
+ * Requires a test token generated from the Firebase Console (7-day TTL).
  *
  * @param token - The test token generated from the Firebase Console.
+ * @throws `pnv/test-session-already-enabled` if called more than once.
+ * @throws `pnv/invalid-test-number-id` if the token is empty, expired, or duplicated.
+ * @see https://firebase.google.com/docs/phone-number-verification
+ * @android
  */
 export function enableTestSession(token: string): Promise<void> {
   return getNativeModule().enableTestSession(token);
@@ -62,10 +70,18 @@ export function enableTestSession(token: string): Promise<void> {
 /**
  * Checks if the device's SIM card(s) support phone number verification.
  *
- * @param simSlot - Optional SIM slot index to query a specific slot instead of all slots.
- * @returns Array of support info results, one per SIM slot (or one entry if simSlot is specified).
+ * @remarks
+ * This method does not require user consent and can be called freely.
+ * Returns one {@link VerificationSupportResult} per SIM slot (or one entry if `simSlot` is specified).
+ *
+ * @param simSlot - Optional 0-based SIM slot index to query a specific slot instead of all slots.
+ * @returns Array of support results, one per SIM slot.
+ * @see https://firebase.google.com/docs/phone-number-verification
+ * @android
  */
-export function getVerificationSupportInfo(simSlot?: number): Promise<VerificationSupportInfo[]> {
+export function getVerificationSupportInfo(
+  simSlot?: number,
+): Promise<VerificationSupportResult[]> {
   if (simSlot !== undefined) {
     return getNativeModule().getVerificationSupportInfoForSimSlot(simSlot);
   }
@@ -76,9 +92,16 @@ export function getVerificationSupportInfo(simSlot?: number): Promise<Verificati
  * Initiates the phone number verification flow, including user consent and token generation.
  * A consent dialog will be presented to the user.
  *
+ * @remarks
+ * The app should prepare the user for the consent screen before calling this method.
+ *
  * @returns The verified phone number and a JWT token with full claims for server-side validation.
+ * @throws `pnv/carrier-not-supported` if the carrier does not support PNV.
+ * @throws `pnv/activity-context-required` if no foreground Activity is available.
+ * @see https://firebase.google.com/docs/phone-number-verification/android/get-started
+ * @android
  */
-export function getVerifiedPhoneNumber(): Promise<VerifiedPhoneNumberResult> {
+export function getVerifiedPhoneNumber(): Promise<VerifiedPhoneNumberTokenResult> {
   return getNativeModule().getVerifiedPhoneNumber();
 }
 
@@ -88,6 +111,8 @@ export function getVerifiedPhoneNumber(): Promise<VerifiedPhoneNumberResult> {
  *
  * @param nonce - A unique value to prevent replay attacks.
  * @returns The digital credential payload string.
+ * @see https://firebase.google.com/docs/phone-number-verification
+ * @android
  */
 export function getDigitalCredentialPayload(nonce: string): Promise<string> {
   return getNativeModule().getDigitalCredentialPayload(nonce);
@@ -99,9 +124,12 @@ export function getDigitalCredentialPayload(nonce: string): Promise<string> {
  *
  * @param dcApiResponse - The JWT from the Credential Manager response.
  * @returns The verified phone number and a JWT token with full claims for server-side validation.
+ * @throws `pnv/invalid-digital-credential-response` if the response is invalid.
+ * @see https://firebase.google.com/docs/phone-number-verification
+ * @android
  */
 export function exchangeCredentialResponseForPhoneNumber(
   dcApiResponse: string,
-): Promise<VerifiedPhoneNumberResult> {
+): Promise<VerifiedPhoneNumberTokenResult> {
   return getNativeModule().exchangeCredentialResponseForPhoneNumber(dcApiResponse);
 }

packages/phone-number-verification/lib/types/pnv.ts

@@ -18,6 +18,13 @@
 /**
  * Status indicating why a SIM slot does or does not support phone number verification.
  * Maps to the native `VerificationSupportStatus` IntDef constants.
+ *
+ * @remarks
+ * Returned as the {@link VerificationSupportResult.reason} field. Use this to determine
+ * whether to fall back to an alternative verification method (e.g. SMS).
+ *
+ * @see https://firebase.google.com/docs/phone-number-verification
+ * @public
  */
 export type VerificationSupportStatus =
   | 'CAPABILITY_STATUS_UNSPECIFIED'
@@ -28,40 +35,57 @@ export type VerificationSupportStatus =
 
 /**
  * Result describing whether a specific SIM slot supports phone number verification.
+ *
+ * @remarks
+ * Mirrors the native `com.google.firebase.pnv.VerificationSupportResult` class.
+ * One instance is returned per SIM slot when calling {@link getVerificationSupportInfo}.
+ *
+ * @see https://firebase.google.com/docs/phone-number-verification
+ * @public
  */
-export interface VerificationSupportInfo {
+export interface VerificationSupportResult {
   /** Whether this SIM slot supports phone number verification. */
-  isSupported: boolean;
+  readonly isSupported: boolean;
   /** The SIM slot index (0-based). */
-  simSlot: number;
+  readonly simSlot: number;
   /** The carrier identifier string for this SIM slot. */
-  carrierId: string;
+  readonly carrierId: string;
   /** The detailed reason for the support status. */
-  reason: VerificationSupportStatus;
+  readonly reason: VerificationSupportStatus;
 }
 
 /**
  * Result of a successful phone number verification, containing the verified
  * phone number and a JWT token for server-side validation.
+ *
+ * @remarks
+ * Mirrors the native `com.google.firebase.pnv.VerifiedPhoneNumberTokenResult` class.
+ * Returned by {@link getVerifiedPhoneNumber} and {@link exchangeCredentialResponseForPhoneNumber}.
+ *
+ * @see https://firebase.google.com/docs/phone-number-verification
+ * @public
  */
-export interface VerifiedPhoneNumberResult {
-  /** The verified phone number (E.164 format). */
-  phoneNumber: string;
+export interface VerifiedPhoneNumberTokenResult {
+  /** The verified phone number in E.164 format. */
+  readonly phoneNumber: string;
   /** The raw JWT token string for server-side validation. */
-  token: string;
+  readonly token: string;
   /** Token expiration time as Unix epoch seconds. */
-  expirationTimestamp: number;
+  readonly expirationTimestamp: number;
   /** Token issued-at time as Unix epoch seconds. */
-  issuedAtTimestamp: number;
-  /** The nonce from the JWT payload, or null if not present. */
-  nonce: string | null;
-  /** All JWT claims as a key-value map, or null if unavailable. */
-  claims: Record<string, unknown> | null;
+  readonly issuedAtTimestamp: number;
+  /** The nonce from the JWT payload, or `null` if not present. */
+  readonly nonce: string | null;
+  /** All JWT claims as a key-value map, or `null` if unavailable. */
+  readonly claims: Record<string, unknown> | null;
 }
 
 /**
  * Error codes returned by the Firebase Phone Number Verification SDK.
- * These map to `FirebasePnvStatusCodes` constants.
+ * These map to `FirebasePnvStatusCodes` constants from the native SDK.
+ *
+ * @see https://firebase.google.com/docs/phone-number-verification
+ * @public
  */
 export type PnvErrorCode =
   | 'pnv/carrier-not-supported'