@cap-kit/rank 8.0.0

package/android/build.gradle

@@ -0,0 +1,110 @@
+buildscript {
+    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+plugins {
+    id "org.jlleitschuh.gradle.ktlint" version "12.1.1" apply false
+}
+
+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'
+    androidxCoreKTXVersion = project.hasProperty('androidxCoreKTXVersion') ? rootProject.ext.androidxCoreKTXVersion : '1.17.0'
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'kotlin-parcelize'
+apply plugin: 'org.jlleitschuh.gradle.ktlint'
+
+import groovy.json.JsonSlurper
+
+def getPluginVersion() {
+    try {
+        def packageJsonFile = file('../package.json')
+        if (packageJsonFile.exists()) {
+            def packageJson = new JsonSlurper().parseText(packageJsonFile.text)
+            return packageJson.version
+        }
+    } catch (Exception e) {
+        // Ignore errors and fallback
+        logger.info("Exception", e)
+    }
+    return "8.0.0"
+}
+
+def pluginVersion = getPluginVersion()
+
+android {
+    namespace = "io.capkit.rank"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion as Integer : 36
+
+    // AGP 8.0+ disables BuildConfig by default for libraries.
+    // We need to enable it to inject the plugin version.
+    buildFeatures {
+        buildConfig = true
+    }
+
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion as Integer : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion as Integer : 36
+        versionCode 1
+
+        // Dynamic versioning (feature enabled)
+        versionName = pluginVersion
+
+        // Injects the version into the BuildConfig class ONLY if feature is enabled
+        buildConfigField "String", "PLUGIN_VERSION", "\"${pluginVersion}\""
+
+        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
+    }
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+
+    // Google Play Review Library
+    implementation "com.google.android.play:review:2.0.2"
+    // Kotlin extension for ReviewManager
+    implementation "com.google.android.play:review-ktx:2.0.2"
+
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    implementation "androidx.core:core-ktx:$androidxCoreKTXVersion"
+
+    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,16 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+    <queries>
+        <intent>
+            <action android:name="android.intent.action.VIEW" />
+            <data android:scheme="market" />
+        </intent>
+        <intent>
+            <action android:name="android.intent.action.VIEW" />
+            <data android:scheme="https" android:host="play.google.com" />
+        </intent>
+    </queries>
+
+    <application>
+    </application>
+</manifest>

package/android/src/main/java/io/capkit/rank/RankConfig.kt

@@ -0,0 +1,72 @@
+package io.capkit.rank
+
+import android.content.Context
+import com.getcapacitor.Plugin
+
+/**
+ * Plugin configuration holder for the Rank plugin.
+ *
+ * This class is responsible for reading and parsing static configuration values
+ * defined under the `plugins.Rank` key in `capacitor.config.ts`.
+ *
+ * Architectural rules:
+ * - Read once during plugin initialization in the load() phase.
+ * - Configuration values are read-only at runtime.
+ * - Consumed only by native code.
+ */
+class RankConfig(plugin: Plugin) {
+  // ---------------------------------------------------------------------------
+  // Properties
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Android application context.
+   * Accessible for native implementation components that require system services.
+   */
+  val context: Context = plugin.context
+
+  /**
+   * Enables verbose native logging via RankLogger.
+   *
+   * When true, additional debug information and lifecycle events are printed to Logcat.
+   * Default: false
+   */
+  val verboseLogging: Boolean
+
+  /**
+   * The Android Package Name used for Play Store redirection.
+   *
+   * If provided, this value overrides the host application's package name
+   * during store navigation.
+   * Default: null (falls back to host app package)
+   */
+  val androidPackageName: String?
+
+  /**
+   * Global policy for review request resolution.
+   *
+   * If true, the `requestReview` method resolves the promise immediately
+   * without waiting for the Google Play review flow to complete.
+   * Default: false
+   */
+  val fireAndForget: Boolean
+
+  // ---------------------------------------------------------------------------
+  // Initialization
+  // ---------------------------------------------------------------------------
+
+  init {
+    // Access the plugin-specific configuration object
+    val config = plugin.getConfig()
+
+    // Extract verboseLogging flag
+    verboseLogging = config.getBoolean("verboseLogging", false)
+
+    // Extract and validate the Android Package Name
+    val apm = config.getString("androidPackageName")
+    androidPackageName = if (!apm.isNullOrBlank()) apm else null
+
+    // Extract the fireAndForget resolution policy
+    fireAndForget = config.getBoolean("fireAndForget", false)
+  }
+}

package/android/src/main/java/io/capkit/rank/RankError.kt

@@ -0,0 +1,40 @@
+package io.capkit.rank
+
+/**
+ * Native error model for the Rank plugin (Android).
+ *
+ * Architectural rules:
+ * - Must NOT reference Capacitor APIs
+ * - Must NOT reference JavaScript
+ * - Must be throwable from the Impl layer
+ * - Mapping to JS-facing error codes happens ONLY in the Plugin layer
+ */
+sealed class RankError(
+  message: String,
+) : Throwable(message) {
+  /**
+   * Feature or capability is not available
+   * due to device or configuration limitations.
+   */
+  class Unavailable(message: String) :
+    RankError(message)
+
+  /**
+   * Required permission was denied or not granted.
+   */
+  class PermissionDenied(message: String) :
+    RankError(message)
+
+  /**
+   * Plugin failed to initialize or perform
+   * a required operation.
+   */
+  class InitFailed(message: String) :
+    RankError(message)
+
+  /**
+   * Invalid or unsupported input was provided.
+   */
+  class UnknownType(message: String) :
+    RankError(message)
+}

package/android/src/main/java/io/capkit/rank/RankImpl.kt

@@ -0,0 +1,240 @@
+package io.capkit.rank
+
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import com.google.android.play.core.review.ReviewManagerFactory
+import io.capkit.rank.utils.RankLogger
+
+/**
+ * Platform-specific native implementation for the Rank plugin.
+ *
+ * This class contains pure Android logic and MUST NOT depend directly on
+ * Capacitor bridge APIs or PluginCall objects.
+ *
+ * Responsibilities:
+ * - Orchestrating the Google Play Review SDK.
+ * - Managing Intent-based Store navigation.
+ * - Translating configuration into native behavior.
+ */
+class RankImpl(
+  private val context: Context,
+) {
+  // ---------------------------------------------------------------------------
+  // Properties
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Cached plugin configuration container.
+   * Provided once during initialization via [updateConfig].
+   */
+  private lateinit var config: RankConfig
+
+  // ---------------------------------------------------------------------------
+  // Configuration
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Applies the plugin configuration to the implementation layer.
+   *
+   * This method MUST be called exactly once during the plugin [RankPlugin.load]
+   * phase. It initializes internal state and configures logging verbosity.
+   *
+   * @param newConfig The immutable configuration instance.
+   */
+  fun updateConfig(newConfig: RankConfig) {
+    this.config = newConfig
+    RankLogger.verbose = newConfig.verboseLogging
+    RankLogger.debug(
+      "Configuration applied. Verbose logging:",
+      newConfig.verboseLogging.toString(),
+    )
+  }
+
+  // ---------------------------------------------------------------------------
+  // Availability check
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Checks whether the In-App Review feature is available on this device.
+   *
+   * This is a semantic availability check intended for UI decisions.
+   * Internally, it delegates to the diagnostic environment check.
+   */
+  fun isAvailable(onResult: (Boolean) -> Unit) {
+    checkReviewEnvironment { canRequest ->
+      onResult(canRequest)
+    }
+  }
+
+  /**
+   * Performs a diagnostic check for the Google Play Review environment.
+   *
+   * This verifies whether Google Play Services can provide
+   * a ReviewInfo instance for the current application and device.
+   *
+   * No UI is triggered by this operation.
+   */
+  fun checkReviewEnvironment(onResult: (Boolean) -> Unit) {
+    val manager = ReviewManagerFactory.create(context)
+    val request = manager.requestReviewFlow()
+
+    request.addOnCompleteListener { task ->
+      onResult(task.isSuccessful)
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Pre-warm Logic
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Cached ReviewInfo object to speed up the review flow display.
+   */
+  private var cachedReviewInfo: com.google.android.play.core.review.ReviewInfo? = null
+
+  /**
+   * Pre-fetches the ReviewInfo from Google Play Services.
+   * This should be called early (e.g., during plugin load).
+   */
+  fun preloadReviewInfo() {
+    val manager = ReviewManagerFactory.create(context)
+    val request = manager.requestReviewFlow()
+    request.addOnCompleteListener { task ->
+      if (task.isSuccessful) {
+        cachedReviewInfo = task.result
+        RankLogger.debug("ReviewInfo pre-loaded successfully.")
+      } else {
+        RankLogger.debug("ReviewInfo pre-load failed.")
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // In-App Review Logic
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Triggers the Google Play In-App Review flow.
+   * Uses the cached ReviewInfo if available to ensure an immediate prompt.
+   *
+   * @param activity The current Android Activity required to display the UI.
+   * @param onComplete Callback invoked when the flow completes or fails.
+   */
+  fun requestReview(
+    activity: Activity,
+    onComplete: (Exception?) -> Unit,
+  ) {
+    val manager = ReviewManagerFactory.create(context)
+
+    // Use cache if available, otherwise fetch new info on the fly
+    if (cachedReviewInfo != null) {
+      val flow = manager.launchReviewFlow(activity, cachedReviewInfo!!)
+      flow.addOnCompleteListener { _ ->
+        cachedReviewInfo = null // Clear cache after use to prevent reuse of expired info
+        onComplete(null)
+      }
+    } else {
+      val request = manager.requestReviewFlow()
+      request.addOnCompleteListener { task ->
+        if (task.isSuccessful) {
+          val reviewInfo = task.result
+          val flow = manager.launchReviewFlow(activity, reviewInfo)
+          flow.addOnCompleteListener { _ -> onComplete(null) }
+        } else {
+          onComplete(task.exception)
+        }
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Store Navigation Logic
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Opens the Google Play Store page for the specified package.
+   *
+   * It attempts to use the "market://" URI scheme first to open the native
+   * Play Store app. If the app is missing, it falls back to a browser-based
+   * "https://" URL.
+   *
+   * @param packageName The application package name. Defaults to the host app if null.
+   */
+  fun openStore(packageName: String?) {
+    val targetPackage = packageName ?: context.packageName
+
+    // Construct the native market Intent
+    val intent =
+      Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=$targetPackage")).apply {
+        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+      }
+
+    try {
+      context.startActivity(intent)
+    } catch (e: Exception) {
+      // Fallback to web browser if Play Store application is unavailable
+      val webIntent =
+        Intent(
+          Intent.ACTION_VIEW,
+          Uri.parse("https://play.google.com/store/apps/details?id=$targetPackage"),
+        ).apply {
+          addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        }
+      context.startActivity(webIntent)
+    }
+  }
+
+  /**
+   * Opens the Google Play Store listing for a specific application ID.
+   *
+   * @param appId The Android package name or application ID to display.
+   */
+  fun openStoreListing(appId: String) {
+    val intent =
+      Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=$appId")).apply {
+        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+      }
+    context.startActivity(intent)
+  }
+
+  /**
+   * Launches the Google Play Store search results for the provided terms.
+   *
+   * @param terms The search query string.
+   */
+  fun search(terms: String) {
+    val intent =
+      Intent(Intent.ACTION_VIEW, Uri.parse("market://search?q=$terms")).apply {
+        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+      }
+    context.startActivity(intent)
+  }
+
+  /**
+   * Navigates to a specific developer's page on the Google Play Store.
+   *
+   * @param devId The unique developer identifier (numeric or string ID).
+   */
+  fun openDevPage(devId: String) {
+    val intent =
+      Intent(Intent.ACTION_VIEW, Uri.parse("https://play.google.com/store/apps/dev?id=$devId")).apply {
+        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+      }
+    context.startActivity(intent)
+  }
+
+  /**
+   * Opens a curated collection or category on the Google Play Store.
+   *
+   * @param name The collection identifier (e.g., "featured", "editors_choice").
+   */
+  fun openCollection(name: String) {
+    val intent =
+      Intent(Intent.ACTION_VIEW, Uri.parse("https://play.google.com/store/apps/collection/$name")).apply {
+        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+      }
+    context.startActivity(intent)
+  }
+}