@capgo/capacitor-android-age-signals 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Capgo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @capgo/capacitor-android-age-signals
+<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">➡️ Ship Instant Updates with Capgo</a></h2>
+  <h2><a href="https://capgo.app/consulting/?ref=plugin">Missing a feature? We’ll build the plugin for you 💪</a></h2>
+</div>
+
+Capacitor wrapper for the Google Play Age Signals API. Detect supervised accounts, guardian approvals, and verified users directly from your app (Android only).
+
+## Documentation
+
+Authoritative docs live inside this repo for now. Explore the TypeScript definitions in `src/definitions.ts` and the Android implementation under `android/` for platform behavior. Run the included example app for an end-to-end walkthrough.
+
+## Install
+
+```bash
+npm install @capgo/capacitor-android-age-signals
+npx cap sync android
+```
+
+Google Play Age Signals is available only on Android phones with the Play Store installed.
+
+## Usage
+
+```ts
+import { AgeSignals } from '@capgo/capacitor-android-age-signals';
+import { UserStatus } from '@capgo/capacitor-android-age-signals';
+
+const result = await AgeSignals.checkAgeSignals();
+
+if (result.userStatus === UserStatus.Supervised) {
+  console.info(`Supervised user aged between ${result.ageLower} and ${result.ageUpper}`);
+} else if (result.userStatus === UserStatus.Verified) {
+  console.info('User is 18+ and verified by Google.');
+} else {
+  console.warn('No definitive age signal returned.');
+}
+```
+
+## API
+
+<docgen-index>
+
+* [`checkAgeSignals()`](#checkagesignals)
+* [Interfaces](#interfaces)
+* [Enums](#enums)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+Capacitor interface for retrieving Play Age Signals.
+
+### checkAgeSignals()
+
+```typescript
+checkAgeSignals() => Promise<CheckAgeSignalsResult>
+```
+
+Request the current Play Age Signals for the active user.
+
+Only available on Android devices with Google Play installed.
+
+**Returns:** <code>Promise&lt;<a href="#checkagesignalsresult">CheckAgeSignalsResult</a>&gt;</code>
+
+**Since:** 0.0.1
+
+--------------------
+
+
+### Interfaces
+
+
+#### CheckAgeSignalsResult
+
+Structured result returned by {@link AgeSignalsPlugin.checkAgeSignals}.
+
+| Prop                         | Type                                              | Description                                                                                                                                                                                                              | Since |
+| ---------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
+| **`userStatus`**             | <code><a href="#userstatus">UserStatus</a></code> | The user's verification status as reported by Google Play.                                                                                                                                                               | 0.0.1 |
+| **`ageLower`**               | <code>number</code>                               | Inclusive lower bound of the supervised user's age range. Present only when `userStatus` is `SUPERVISED`, `SUPERVISED_APPROVAL_PENDING`, or `SUPERVISED_APPROVAL_DENIED`.                                                | 0.0.1 |
+| **`ageUpper`**               | <code>number</code>                               | Inclusive upper bound of the supervised user's age range. Present only when `userStatus` is `SUPERVISED`, `SUPERVISED_APPROVAL_PENDING`, or `SUPERVISED_APPROVAL_DENIED` and the user's age is reported as less than 18. | 0.0.1 |
+| **`mostRecentApprovalDate`** | <code>string</code>                               | Effective date for the most recent significant change that received guardian approval. Present only when `userStatus` is `SUPERVISED_APPROVAL_PENDING` or `SUPERVISED_APPROVAL_DENIED`.                                  | 0.0.1 |
+| **`installId`**              | <code>string</code>                               | Identifier assigned to supervised installs in Google Play for revocation notifications. Present only when `userStatus` is `SUPERVISED`, `SUPERVISED_APPROVAL_PENDING`, or `SUPERVISED_APPROVAL_DENIED`.                  | 0.0.1 |
+
+
+### Enums
+
+
+#### UserStatus
+
+| Members                         | Value                                      | Description                                                                                                                                                                                                               | Since |
+| ------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`Verified`**                  | <code>'VERIFIED'</code>                    | The user is over 18 and their age has been verified by Google.                                                                                                                                                            | 0.0.1 |
+| **`Supervised`**                | <code>'SUPERVISED'</code>                  | The user has a supervised Google Account managed by a guardian. Use `ageLower` and `ageUpper` to determine the user's age range.                                                                                          | 0.0.1 |
+| **`SupervisedApprovalPending`** | <code>'SUPERVISED_APPROVAL_PENDING'</code> | The supervised user has pending significant changes awaiting guardian approval. Use `ageLower` and `ageUpper` to determine the user's age range and `mostRecentApprovalDate` to identify the most recent approved change. | 0.0.1 |
+| **`SupervisedApprovalDenied`**  | <code>'SUPERVISED_APPROVAL_DENIED'</code>  | The supervised user's guardian denied one or more significant changes. Use `ageLower` and `ageUpper` to determine the user's age range and `mostRecentApprovalDate` to identify the last approved change.                 | 0.0.1 |
+| **`Unknown`**                   | <code>'UNKNOWN'</code>                     | The user is not verified or supervised in supported regions. You should prompt the user to resolve their status in the Play Store.                                                                                        | 0.0.1 |
+| **`Empty`**                     | <code>'EMPTY'</code>                       | All other users return this value.                                                                                                                                                                                        | 0.0.1 |
+
+</docgen-api>

package/android/build.gradle

@@ -0,0 +1,59 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
+    androidPlayAgeSignalsVersion = project.hasProperty('androidPlayAgeSignalsVersion') ? rootProject.ext.androidPlayAgeSignalsVersion : '0.0.1-beta01'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.2'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "app.capgo.androidagesignals"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        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')
+    implementation "com.google.android.play:age-signals:$androidPlayAgeSignalsVersion"
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    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,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="app.capgo.androidagesignals" />

package/android/src/main/java/app/capgo/androidagesignals/AgeSignals.java

@@ -0,0 +1,75 @@
+package app.capgo.androidagesignals;
+
+import androidx.annotation.NonNull;
+import com.google.android.gms.tasks.Task;
+import com.google.android.play.agesignals.AgeSignalsManager;
+import com.google.android.play.agesignals.AgeSignalsManagerFactory;
+import com.google.android.play.agesignals.AgeSignalsRequest;
+import com.google.android.play.agesignals.AgeSignalsResult;
+import app.capgo.androidagesignals.classes.CustomExceptions;
+import app.capgo.androidagesignals.classes.results.CheckAgeSignalsResult;
+import app.capgo.androidagesignals.interfaces.NonEmptyResultCallback;
+
+public class AgeSignals {
+
+    @NonNull
+    private final AgeSignalsPlugin plugin;
+
+    public AgeSignals(@NonNull AgeSignalsPlugin plugin) {
+        this.plugin = plugin;
+    }
+
+    public void checkAgeSignals(@NonNull NonEmptyResultCallback<CheckAgeSignalsResult> callback) {
+        AgeSignalsManager manager = AgeSignalsManagerFactory.create(plugin.getActivity());
+        AgeSignalsRequest request = AgeSignalsRequest.builder().build();
+
+        Task<AgeSignalsResult> task = manager.checkAgeSignals(request);
+        task.addOnSuccessListener(ageSignalsResult -> {
+            try {
+                CheckAgeSignalsResult result = new CheckAgeSignalsResult(ageSignalsResult);
+                callback.success(result);
+            } catch (Exception exception) {
+                callback.error(exception);
+            }
+        });
+        task.addOnFailureListener(exception -> {
+            Exception mapped = mapErrorToException(exception);
+            callback.error(mapped);
+        });
+    }
+
+    @NonNull
+    private Exception mapErrorToException(@NonNull Exception exception) {
+        if (!(exception instanceof com.google.android.gms.common.api.ApiException)) {
+            return exception;
+        }
+
+        com.google.android.gms.common.api.ApiException apiException = (com.google.android.gms.common.api.ApiException) exception;
+        int statusCode = apiException.getStatusCode();
+
+        switch (statusCode) {
+            case 25000:
+                return CustomExceptions.API_NOT_AVAILABLE;
+            case 25001:
+                return CustomExceptions.PLAY_STORE_NOT_FOUND;
+            case 25002:
+                return CustomExceptions.NETWORK_ERROR;
+            case 25003:
+                return CustomExceptions.PLAY_SERVICES_NOT_FOUND;
+            case 25004:
+                return CustomExceptions.CANNOT_BIND_TO_SERVICE;
+            case 25005:
+                return CustomExceptions.PLAY_STORE_VERSION_OUTDATED;
+            case 25006:
+                return CustomExceptions.PLAY_SERVICES_VERSION_OUTDATED;
+            case 25007:
+                return CustomExceptions.CLIENT_TRANSIENT_ERROR;
+            case 25008:
+                return CustomExceptions.APP_NOT_OWNED;
+            case 25009:
+                return CustomExceptions.INTERNAL_ERROR;
+            default:
+                return exception;
+        }
+    }
+}

package/android/src/main/java/app/capgo/androidagesignals/AgeSignalsPlugin.java

@@ -0,0 +1,78 @@
+package app.capgo.androidagesignals;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Logger;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import app.capgo.androidagesignals.classes.results.CheckAgeSignalsResult;
+import app.capgo.androidagesignals.interfaces.NonEmptyResultCallback;
+import app.capgo.androidagesignals.interfaces.Result;
+
+@CapacitorPlugin(name = "AgeSignals")
+public class AgeSignalsPlugin extends Plugin {
+    public static final String TAG = "AgeSignals";
+    private static final String ERROR_UNKNOWN = "An unknown error occurred.";
+
+    private AgeSignals implementation;
+
+    @Override
+    public void load() {
+        implementation = new AgeSignals(this);
+    }
+
+    @PluginMethod
+    public void checkAgeSignals(@NonNull PluginCall call) {
+        try {
+            NonEmptyResultCallback<CheckAgeSignalsResult> callback = new NonEmptyResultCallback<>() {
+                @Override
+                public void success(@NonNull CheckAgeSignalsResult result) {
+                    resolveCall(call, result);
+                }
+
+                @Override
+                public void error(@NonNull Exception exception) {
+                    rejectCall(call, exception);
+                }
+            };
+
+            if (implementation == null) {
+                rejectCall(call, new Exception("Plugin not initialized."));
+                return;
+            }
+
+            implementation.checkAgeSignals(callback);
+        } catch (Exception exception) {
+            rejectCall(call, exception);
+        }
+    }
+
+    private void rejectCall(@NonNull PluginCall call, @NonNull Exception exception) {
+        String message = exception.getMessage();
+        if (message == null || message.isEmpty()) {
+            message = ERROR_UNKNOWN;
+        }
+        Logger.error(TAG, message, exception);
+
+        if (exception instanceof app.capgo.androidagesignals.classes.CustomException) {
+            JSObject error = new JSObject();
+            app.capgo.androidagesignals.classes.CustomException customException = (app.capgo.androidagesignals.classes.CustomException) exception;
+            error.put("code", customException.getCode());
+            error.put("message", message);
+            call.reject(message, customException.getCode(), error);
+        } else {
+            call.reject(message);
+        }
+    }
+
+    private void resolveCall(@NonNull PluginCall call, @Nullable Result result) {
+        if (result == null) {
+            call.resolve();
+        } else {
+            call.resolve(result.toJSObject());
+        }
+    }
+}

package/android/src/main/java/app/capgo/androidagesignals/classes/CustomException.java

@@ -0,0 +1,19 @@
+package app.capgo.androidagesignals.classes;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+public class CustomException extends Exception {
+    @Nullable
+    private final String code;
+
+    public CustomException(@Nullable String code, @NonNull String message) {
+        super(message);
+        this.code = code;
+    }
+
+    @Nullable
+    public String getCode() {
+        return code;
+    }
+}

package/android/src/main/java/app/capgo/androidagesignals/classes/CustomExceptions.java

@@ -0,0 +1,43 @@
+package app.capgo.androidagesignals.classes;
+
+public final class CustomExceptions {
+    private CustomExceptions() {}
+
+    public static final CustomException API_NOT_AVAILABLE = new CustomException(
+        "API_NOT_AVAILABLE",
+        "The Play Age Signals API is not available. The installed Play Store might be outdated."
+    );
+    public static final CustomException PLAY_STORE_NOT_FOUND = new CustomException(
+        "PLAY_STORE_NOT_FOUND",
+        "Google Play Store is not installed on this device."
+    );
+    public static final CustomException NETWORK_ERROR = new CustomException("NETWORK_ERROR", "No available network connection.");
+    public static final CustomException PLAY_SERVICES_NOT_FOUND = new CustomException(
+        "PLAY_SERVICES_NOT_FOUND",
+        "Google Play services is missing or out of date."
+    );
+    public static final CustomException CANNOT_BIND_TO_SERVICE = new CustomException(
+        "CANNOT_BIND_TO_SERVICE",
+        "Failed to bind to the Google Play service. The Play Store may be outdated or resources are low."
+    );
+    public static final CustomException PLAY_STORE_VERSION_OUTDATED = new CustomException(
+        "PLAY_STORE_VERSION_OUTDATED",
+        "Update Google Play Store to continue."
+    );
+    public static final CustomException PLAY_SERVICES_VERSION_OUTDATED = new CustomException(
+        "PLAY_SERVICES_VERSION_OUTDATED",
+        "Update Google Play services to continue."
+    );
+    public static final CustomException CLIENT_TRANSIENT_ERROR = new CustomException(
+        "CLIENT_TRANSIENT_ERROR",
+        "A transient error occurred on the device. Retry the request."
+    );
+    public static final CustomException APP_NOT_OWNED = new CustomException(
+        "APP_NOT_OWNED",
+        "The app was not installed from Google Play."
+    );
+    public static final CustomException INTERNAL_ERROR = new CustomException(
+        "INTERNAL_ERROR",
+        "An unknown internal error occurred."
+    );
+}

package/android/src/main/java/app/capgo/androidagesignals/classes/results/CheckAgeSignalsResult.java

@@ -0,0 +1,72 @@
+package app.capgo.androidagesignals.classes.results;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import com.getcapacitor.JSObject;
+import com.google.android.play.agesignals.AgeSignalsResult;
+import app.capgo.androidagesignals.enums.UserStatus;
+import app.capgo.androidagesignals.interfaces.Result;
+
+public class CheckAgeSignalsResult implements Result {
+    @NonNull
+    private final UserStatus userStatus;
+
+    @Nullable
+    private final Integer ageLower;
+
+    @Nullable
+    private final Integer ageUpper;
+
+    @Nullable
+    private final String mostRecentApprovalDate;
+
+    @Nullable
+    private final String installId;
+
+    public CheckAgeSignalsResult(@NonNull AgeSignalsResult ageSignalsResult) {
+        this.userStatus = mapUserStatus(ageSignalsResult.userStatus().toString());
+        this.ageLower = ageSignalsResult.ageLower();
+        this.ageUpper = ageSignalsResult.ageUpper();
+        this.mostRecentApprovalDate =
+            ageSignalsResult.mostRecentApprovalDate() != null ? ageSignalsResult.mostRecentApprovalDate().toString() : null;
+        this.installId = ageSignalsResult.installId();
+    }
+
+    @Override
+    @NonNull
+    public JSObject toJSObject() {
+        JSObject result = new JSObject();
+        result.put("userStatus", userStatus.name());
+        if (ageLower != null) {
+            result.put("ageLower", ageLower);
+        }
+        if (ageUpper != null) {
+            result.put("ageUpper", ageUpper);
+        }
+        if (mostRecentApprovalDate != null) {
+            result.put("mostRecentApprovalDate", mostRecentApprovalDate);
+        }
+        if (installId != null) {
+            result.put("installId", installId);
+        }
+        return result;
+    }
+
+    @NonNull
+    private UserStatus mapUserStatus(@NonNull String status) {
+        switch (status) {
+            case "VERIFIED":
+                return UserStatus.VERIFIED;
+            case "SUPERVISED":
+                return UserStatus.SUPERVISED;
+            case "SUPERVISED_APPROVAL_PENDING":
+                return UserStatus.SUPERVISED_APPROVAL_PENDING;
+            case "SUPERVISED_APPROVAL_DENIED":
+                return UserStatus.SUPERVISED_APPROVAL_DENIED;
+            case "UNKNOWN":
+                return UserStatus.UNKNOWN;
+            default:
+                return UserStatus.EMPTY;
+        }
+    }
+}

package/android/src/main/java/app/capgo/androidagesignals/enums/UserStatus.java

@@ -0,0 +1,10 @@
+package app.capgo.androidagesignals.enums;
+
+public enum UserStatus {
+    VERIFIED,
+    SUPERVISED,
+    SUPERVISED_APPROVAL_PENDING,
+    SUPERVISED_APPROVAL_DENIED,
+    UNKNOWN,
+    EMPTY
+}

package/android/src/main/java/app/capgo/androidagesignals/interfaces/Callback.java

@@ -0,0 +1,5 @@
+package app.capgo.androidagesignals.interfaces;
+
+public interface Callback {
+    void error(Exception exception);
+}

package/android/src/main/java/app/capgo/androidagesignals/interfaces/NonEmptyResultCallback.java

@@ -0,0 +1,7 @@
+package app.capgo.androidagesignals.interfaces;
+
+import androidx.annotation.NonNull;
+
+public interface NonEmptyResultCallback<T extends Result> extends Callback {
+    void success(@NonNull T result);
+}

package/android/src/main/java/app/capgo/androidagesignals/interfaces/Result.java

@@ -0,0 +1,7 @@
+package app.capgo.androidagesignals.interfaces;
+
+import com.getcapacitor.JSObject;
+
+public interface Result {
+    JSObject toJSObject();
+}