@capgo/capacitor-android-sms-retriever 8.0.1

package/README.md

@@ -0,0 +1,312 @@
+# @capgo/capacitor-android-sms-retriever
+
+<a href="https://capgo.app/"><img src="https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png" alt="Capgo - Instant updates for Capacitor" /></a>
+
+<div align="center">
+  <h2><a href="https://capgo.app/?ref=plugin_android_sms_retriever">Get instant updates for your app with Capgo</a></h2>
+  <h2><a href="https://capgo.app/consulting/?ref=plugin_android_sms_retriever">Missing a feature? We can build the plugin for you</a></h2>
+</div>
+
+Android-only Capacitor plugin for Google Play services SMS Retriever and Phone Number Hint APIs.
+
+## Install
+
+```bash
+bun add @capgo/capacitor-android-sms-retriever
+bunx cap sync android
+```
+
+## Android
+
+This plugin does not request SMS permissions. SMS retrieval uses Google Play services and waits for one matching verification SMS for up to five minutes.
+
+The verification SMS must include the app hash returned by `getHashString()`.
+
+## Usage
+
+```typescript
+import { AndroidSmsRetriever } from '@capgo/capacitor-android-sms-retriever';
+
+const { hash } = await AndroidSmsRetriever.getHashString();
+console.log('SMS hash:', hash);
+
+const received = await AndroidSmsRetriever.addListener('smsReceived', ({ message }) => {
+  console.log('Verification SMS:', message);
+});
+
+await AndroidSmsRetriever.addListener('smsRetrieverTimeout', () => {
+  console.log('SMS Retriever timed out');
+});
+
+await AndroidSmsRetriever.startWatch();
+
+// Later, if needed:
+await AndroidSmsRetriever.stopWatch();
+await received.remove();
+```
+
+```typescript
+const { phoneNumber } = await AndroidSmsRetriever.getPhoneNumber();
+console.log(phoneNumber);
+```
+
+## API
+
+<docgen-index>
+
+* [`startWatch()`](#startwatch)
+* [`stopWatch()`](#stopwatch)
+* [`getHashString()`](#gethashstring)
+* [`getPhoneNumber()`](#getphonenumber)
+* [`addListener('smsReceived', ...)`](#addlistenersmsreceived-)
+* [`addListener('smsRetrieverTimeout', ...)`](#addlistenersmsretrievertimeout-)
+* [`addListener('smsRetrieverError', ...)`](#addlistenersmsretrievererror-)
+* [`removeAllListeners()`](#removealllisteners)
+* [`getPluginVersion()`](#getpluginversion)
+* [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+Android-only Capacitor plugin for Google Play services SMS Retriever and Phone Number Hint APIs.
+
+### startWatch()
+
+```typescript
+startWatch() => Promise<StartWatchResult>
+```
+
+Start listening for one verification SMS through Android's SMS Retriever API.
+
+Android stops listening automatically when a matching message arrives or after the
+five-minute SMS Retriever timeout. No SMS permissions are required.
+
+**Returns:** <code>Promise&lt;<a href="#startwatchresult">StartWatchResult</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+### stopWatch()
+
+```typescript
+stopWatch() => Promise<StopWatchResult>
+```
+
+Stop the active SMS Retriever watch, if any.
+
+**Returns:** <code>Promise&lt;<a href="#stopwatchresult">StopWatchResult</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+### getHashString()
+
+```typescript
+getHashString() => Promise<GetHashStringResult>
+```
+
+Get the 11-character app hash for the installed app signature.
+
+Generate this once for the signing key used to distribute the app and append it
+to verification SMS messages.
+
+**Returns:** <code>Promise&lt;<a href="#gethashstringresult">GetHashStringResult</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+### getPhoneNumber()
+
+```typescript
+getPhoneNumber() => Promise<GetPhoneNumberResult>
+```
+
+Show Android's Phone Number Hint UI and return the user-selected SIM-based phone number.
+
+**Returns:** <code>Promise&lt;<a href="#getphonenumberresult">GetPhoneNumberResult</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+### addListener('smsReceived', ...)
+
+```typescript
+addListener(eventName: 'smsReceived', listenerFunc: (event: SmsReceivedEvent) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for a verification SMS received after {@link startWatch}.
+
+| Param              | Type                                                                              |
+| ------------------ | --------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'smsReceived'</code>                                                        |
+| **`listenerFunc`** | <code>(event: <a href="#smsreceivedevent">SmsReceivedEvent</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+### addListener('smsRetrieverTimeout', ...)
+
+```typescript
+addListener(eventName: 'smsRetrieverTimeout', listenerFunc: () => void) => Promise<PluginListenerHandle>
+```
+
+Listen for the five-minute SMS Retriever timeout.
+
+| Param              | Type                               |
+| ------------------ | ---------------------------------- |
+| **`eventName`**    | <code>'smsRetrieverTimeout'</code> |
+| **`listenerFunc`** | <code>() =&gt; void</code>         |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+### addListener('smsRetrieverError', ...)
+
+```typescript
+addListener(eventName: 'smsRetrieverError', listenerFunc: (event: SmsRetrieverErrorEvent) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for SMS Retriever runtime errors after {@link startWatch}.
+
+| Param              | Type                                                                                          |
+| ------------------ | --------------------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'smsRetrieverError'</code>                                                              |
+| **`listenerFunc`** | <code>(event: <a href="#smsretrievererrorevent">SmsRetrieverErrorEvent</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+### removeAllListeners()
+
+```typescript
+removeAllListeners() => Promise<void>
+```
+
+Remove all registered listeners for this plugin.
+
+**Since:** 8.0.0
+
+--------------------
+
+
+### getPluginVersion()
+
+```typescript
+getPluginVersion() => Promise<PluginVersionResult>
+```
+
+Get the native Capacitor plugin version.
+
+**Returns:** <code>Promise&lt;<a href="#pluginversionresult">PluginVersionResult</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+### Interfaces
+
+
+#### StartWatchResult
+
+Result returned when SMS Retriever watching starts.
+
+| Prop         | Type                                                                        | Description                        | Since |
+| ------------ | --------------------------------------------------------------------------- | ---------------------------------- | ----- |
+| **`status`** | <code><a href="#smsretrieverstartstatus">SmsRetrieverStartStatus</a></code> | Native status returned by Android. | 8.0.0 |
+
+
+#### StopWatchResult
+
+Result returned when SMS Retriever watching stops.
+
+| Prop         | Type                              | Description                        | Since |
+| ------------ | --------------------------------- | ---------------------------------- | ----- |
+| **`status`** | <code>'SMS_RETRIEVER_DONE'</code> | Native status returned by Android. | 8.0.0 |
+
+
+#### GetHashStringResult
+
+Result returned by {@link AndroidSmsRetrieverPlugin.getHashString}.
+
+| Prop       | Type                | Description                                                                   | Since |
+| ---------- | ------------------- | ----------------------------------------------------------------------------- | ----- |
+| **`hash`** | <code>string</code> | The 11-character app hash that must be appended to verification SMS messages. | 8.0.0 |
+
+
+#### GetPhoneNumberResult
+
+Result returned by {@link AndroidSmsRetrieverPlugin.getPhoneNumber}.
+
+| Prop              | Type                | Description                                                            | Since |
+| ----------------- | ------------------- | ---------------------------------------------------------------------- | ----- |
+| **`phoneNumber`** | <code>string</code> | Phone number selected by the user from Android's Phone Number Hint UI. | 8.0.0 |
+
+
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+#### SmsReceivedEvent
+
+SMS Retriever message event payload.
+
+| Prop          | Type                | Description                                                            | Since |
+| ------------- | ------------------- | ---------------------------------------------------------------------- | ----- |
+| **`message`** | <code>string</code> | Full verification SMS message received by Android's SMS Retriever API. | 8.0.0 |
+
+
+#### SmsRetrieverErrorEvent
+
+SMS Retriever error event payload.
+
+| Prop          | Type                | Description                                                | Since |
+| ------------- | ------------------- | ---------------------------------------------------------- | ----- |
+| **`message`** | <code>string</code> | Error message returned by Android or Google Play services. | 8.0.0 |
+
+
+#### PluginVersionResult
+
+Plugin version payload.
+
+| Prop          | Type                | Description                                                 | Since |
+| ------------- | ------------------- | ----------------------------------------------------------- | ----- |
+| **`version`** | <code>string</code> | Version identifier returned by the platform implementation. | 8.0.0 |
+
+
+### Type Aliases
+
+
+#### SmsRetrieverStartStatus
+
+Status values returned by {@link AndroidSmsRetrieverPlugin.startWatch}.
+
+<code>'SMS_RETRIEVER_STARTED' | 'SMS_RETRIEVER_ALREADY_STARTED'</code>
+
+</docgen-api>

package/android/build.gradle

@@ -0,0 +1,63 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    playServicesAuthVersion = project.hasProperty('playServicesAuthVersion') ? rootProject.ext.playServicesAuthVersion : '21.5.1'
+    playServicesAuthApiPhoneVersion = project.hasProperty('playServicesAuthApiPhoneVersion') ? rootProject.ext.playServicesAuthApiPhoneVersion : '18.3.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace = "app.capgo.androidsmsretriever"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    lint {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    annotationProcessor project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "com.google.android.gms:play-services-auth:$playServicesAuthVersion"
+    implementation "com.google.android.gms:play-services-auth-api-phone:$playServicesAuthApiPhoneVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

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

package/android/src/main/java/app/capgo/androidsmsretriever/AndroidSmsRetriever.java

@@ -0,0 +1,137 @@
+package app.capgo.androidsmsretriever;
+
+import android.content.Context;
+import android.content.IntentFilter;
+import android.os.Build;
+import com.google.android.gms.auth.api.phone.SmsRetriever;
+import com.google.android.gms.auth.api.phone.SmsRetrieverClient;
+import com.google.android.gms.tasks.Task;
+import java.util.ArrayList;
+
+public class AndroidSmsRetriever {
+
+    public interface StartWatchCallback {
+        void success(String status);
+        void error(String message, Exception exception);
+    }
+
+    public interface SmsRetrieverListener {
+        void onSmsReceived(String message);
+        void onTimeout();
+        void onError(String message);
+    }
+
+    private static final String STATUS_STARTED = "SMS_RETRIEVER_STARTED";
+    private static final String STATUS_ALREADY_STARTED = "SMS_RETRIEVER_ALREADY_STARTED";
+
+    private final Context applicationContext;
+    private SmsBroadcastReceiver smsBroadcastReceiver;
+    private SmsRetrieverListener listener;
+
+    public AndroidSmsRetriever(Context context) {
+        this.applicationContext = context.getApplicationContext();
+    }
+
+    public void setListener(SmsRetrieverListener listener) {
+        this.listener = listener;
+    }
+
+    public void startWatch(StartWatchCallback callback) {
+        if (smsBroadcastReceiver != null) {
+            callback.success(STATUS_ALREADY_STARTED);
+            return;
+        }
+
+        smsBroadcastReceiver = new SmsBroadcastReceiver();
+        smsBroadcastReceiver.setListener(
+            new SmsBroadcastReceiver.Listener() {
+                @Override
+                public void onSmsReceived(String message) {
+                    if (listener != null) {
+                        listener.onSmsReceived(message);
+                    }
+                    unregisterReceiver();
+                }
+
+                @Override
+                public void onTimeout() {
+                    if (listener != null) {
+                        listener.onTimeout();
+                    }
+                    unregisterReceiver();
+                }
+
+                @Override
+                public void onError(String message) {
+                    if (listener != null) {
+                        listener.onError(message);
+                    }
+                    unregisterReceiver();
+                }
+            }
+        );
+
+        SmsRetrieverClient smsRetrieverClient = SmsRetriever.getClient(applicationContext);
+        Task<Void> task = smsRetrieverClient.startSmsRetriever();
+
+        task.addOnSuccessListener((aVoid) -> {
+            try {
+                registerReceiver();
+                callback.success(STATUS_STARTED);
+            } catch (Exception exception) {
+                unregisterReceiver();
+                callback.error("Unable to register SMS Retriever receiver.", exception);
+            }
+        });
+
+        task.addOnFailureListener((exception) -> {
+            unregisterReceiver();
+            callback.error("Unable to start SMS Retriever.", exception);
+        });
+    }
+
+    public void stopWatch() {
+        unregisterReceiver();
+    }
+
+    public String getHashString() {
+        ArrayList<String> appCodes = new AppSignatureHashHelper(applicationContext).getAppSignatures();
+        if (appCodes.isEmpty() || appCodes.get(0) == null) {
+            throw new IllegalStateException("Unable to find package signature hash.");
+        }
+        return appCodes.get(0);
+    }
+
+    private void registerReceiver() {
+        if (smsBroadcastReceiver == null) {
+            throw new IllegalStateException("SMS Retriever receiver is not initialized.");
+        }
+
+        IntentFilter intentFilter = new IntentFilter(SmsRetriever.SMS_RETRIEVED_ACTION);
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            applicationContext.registerReceiver(
+                smsBroadcastReceiver,
+                intentFilter,
+                SmsRetriever.SEND_PERMISSION,
+                null,
+                Context.RECEIVER_EXPORTED
+            );
+        } else {
+            applicationContext.registerReceiver(smsBroadcastReceiver, intentFilter, SmsRetriever.SEND_PERMISSION, null);
+        }
+    }
+
+    private void unregisterReceiver() {
+        if (smsBroadcastReceiver == null) {
+            return;
+        }
+
+        try {
+            applicationContext.unregisterReceiver(smsBroadcastReceiver);
+        } catch (IllegalArgumentException ignored) {
+            // Receiver was already unregistered by Android.
+        } finally {
+            smsBroadcastReceiver = null;
+        }
+    }
+}