@cap-kit/rank 8.0.0

package/ios/Sources/RankPlugin/RankImpl.swift

@@ -0,0 +1,186 @@
+import Foundation
+import StoreKit
+
+/**
+ * Native iOS implementation for the Rank plugin.
+ *
+ * This class contains pure platform logic and is isolated from the Capacitor bridge.
+ * Architectural constraints:
+ * - MUST NOT access CAPPluginCall.
+ * - MUST NOT depend on Capacitor bridge APIs directly.
+ * - MUST perform UI operations on the Main Thread.
+ */
+@objc public final class RankImpl: NSObject {
+
+    // MARK: - Properties
+
+    /// Cached plugin configuration containing logging and behavioral flags.
+    private var config: RankConfig?
+
+    // MARK: - Initialization
+
+    /**
+     * Initializes the implementation instance.
+     */
+    override init() {
+        super.init()
+    }
+
+    // MARK: - Configuration
+
+    /**
+     * Applies static plugin configuration.
+     *
+     * This method MUST be called exactly once from the Plugin bridge layer during `load()`.
+     * It synchronizes the native logger state with the provided configuration.
+     *
+     * - Parameter config: The immutable configuration container.
+     */
+    func applyConfig(_ config: RankConfig) {
+        precondition(
+            self.config == nil,
+            "RankImpl.applyConfig(_:) must be called exactly once"
+        )
+        self.config = config
+        RankLogger.verbose = config.verboseLogging
+
+        RankLogger.debug(
+            "Configuration applied. Verbose logging:",
+            config.verboseLogging
+        )
+    }
+
+    // MARK: - Availability
+
+    /**
+     * Checks if the current iOS version supports the SKStoreReviewController API.
+     * Since the plugin target is iOS 15+, this generally returns true.
+     */
+    @objc public func isAvailable() -> Bool {
+        if #available(iOS 10.3, *) {
+            return true
+        }
+        return false
+    }
+
+    // MARK: - Product Page
+
+    /**
+     * Presents the App Store product page within the application.
+     * * - Parameter appId: The numeric Apple App ID.
+     * - Parameter completion: Callback to signal when the page has been loaded or failed.
+     */
+    @objc public func presentProductPage(appId: String, completion: @escaping (Bool, Error?) -> Void) {
+        let storeViewController = SKStoreProductViewController()
+        let parameters = [SKStoreProductParameterITunesItemIdentifier: appId]
+
+        // UI operations must be on the main thread
+        DispatchQueue.main.async {
+            storeViewController.loadProduct(withParameters: parameters) { success, error in
+                if success {
+                    // Attempt to find the top-most view controller to present the sheet
+                    if let rootVC = UIApplication.shared.windows.first?.rootViewController {
+                        rootVC.present(storeViewController, animated: true) {
+                            completion(true, nil)
+                        }
+                    } else {
+                        completion(false, nil)
+                    }
+                } else {
+                    completion(false, error)
+                }
+            }
+        }
+    }
+
+    // MARK: - Review Methods
+
+    /**
+     * Triggers the native iOS In-App Review prompt.
+     *
+     * Uses the modern `requestReview(in:)` API for iOS 14+ by identifying the active foreground scene.
+     * Fallback logic is provided for older iOS versions (though the plugin target is iOS 15+).
+     *
+     * NOTE: The OS manages the frequency of this prompt; calling this does not guarantee a UI will appear.
+     */
+    @objc public func requestReview() {
+        if #available(iOS 14.0, *) {
+            let activeScene = UIApplication.shared.connectedScenes
+                .compactMap { $0 as? UIWindowScene }
+                .first { $0.activationState == .foregroundActive }
+
+            guard let windowScene = activeScene else {
+                // Diagnostic logging only: review prompt cannot be requested without an active scene
+                RankLogger.error("Cannot request review: no active UIWindowScene found")
+                return
+            }
+
+            RankLogger.debug("Requesting in-app review for active UIWindowScene")
+            SKStoreReviewController.requestReview(in: windowScene)
+        } else {
+            // Legacy fallback (not expected to be used due to iOS 15+ minimum target)
+            RankLogger.debug("Requesting in-app review using legacy API")
+            SKStoreReviewController.requestReview()
+        }
+    }
+
+    // MARK: - Store Navigation
+
+    /**
+     * Opens the App Store page for the specified application ID.
+     *
+     * This method constructs a deep link using the `itms-apps` scheme to direct the user
+     * to the review section of the application's store page.
+     *
+     * - Parameter appId: The numeric Apple App ID (e.g., "123456789").
+     */
+    @objc public func openStore(appId: String) {
+        guard let url = RankUtils.appStoreURL(appId: appId) else {
+            RankLogger.error("Invalid App Store URL for ID: \(appId)")
+            return
+        }
+
+        // RULE: All UI-related operations MUST be dispatched to the main thread.
+        DispatchQueue.main.async {
+            UIApplication.shared.open(url, options: [:]) { success in
+                if success {
+                    RankLogger.debug("App Store opened successfully.")
+                } else {
+                    RankLogger.error("Failed to open App Store URL.")
+                }
+            }
+        }
+    }
+
+    /**
+     * Opens the App Store product page for the specified application ID.
+     *
+     * This method constructs a deep link using the `itms-apps` scheme to direct the user
+     * to the product page of the application in the App Store.
+     *
+     * - Parameter appId: The numeric Apple App ID (e.g., "123456789").
+     */
+    @objc public func openStoreListing(appId: String) {
+        let urlString = "itms-apps://itunes.apple.com/app/id\(appId)"
+        if let url = URL(string: urlString) {
+            DispatchQueue.main.async {
+                UIApplication.shared.open(url)
+            }
+        }
+    }
+
+    /**
+     * Opens the App Store search page with the specified search terms.
+     *
+     * This method constructs a deep link using the `itms-apps` scheme to direct the user
+     * to the search results page in the App Store for the given terms.
+     *
+     * - Parameter terms: The search query string to find relevant apps in the App Store.
+     */
+    @objc public func search(terms: String) {
+        guard let url = RankUtils.searchURL(terms: terms) else { return }
+        DispatchQueue.main.async {
+            UIApplication.shared.open(url)
+        }
+    }
+}

package/ios/Sources/RankPlugin/RankPlugin.swift

@@ -0,0 +1,258 @@
+import Foundation
+import Capacitor
+
+/**
+ * Capacitor bridge for the Rank plugin.
+ *
+ * This class handles the communication between the JavaScript layer and the native iOS implementation.
+ * It is responsible for input validation, configuration merging, and thread safety.
+ */
+@objc(RankPlugin)
+public final class RankPlugin: CAPPlugin, CAPBridgedPlugin {
+
+    // MARK: - Properties
+
+    /// An instance of the implementation class that contains the plugin's core functionality.
+    private let implementation = RankImpl()
+
+    /// Internal storage for the plugin configuration read from capacitor.config.ts.
+    private var config: RankConfig?
+
+    /// The unique identifier for the plugin used by the Capacitor bridge.
+    public let identifier = "RankPlugin"
+
+    /// The name used to reference this plugin in JavaScript (e.g., Rank.requestReview()).
+    public let jsName = "Rank"
+
+    /**
+     * A list of methods exposed by this plugin to the JavaScript layer.
+     * All methods defined here must be implemented with the @objc attribute.
+     - `isAvailable`: Checks if the native review prompt can be shown on the current device.
+     - `requestReview`: Triggers the native iOS In-App Review prompt.
+     - `presentProductPage`: Navigates the user to the App Store product page within the app.
+     - `openStore`: Opens the app's page on the App Store for leaving a review or viewing details.
+     - `getPluginVersion`: A method that returns the version of the plugin.
+     */
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "isAvailable", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "requestReview", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "presentProductPage", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "openStore", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getPluginVersion", returnType: CAPPluginReturnPromise)
+    ]
+
+    // MARK: - Lifecycle
+
+    /**
+     * Plugin lifecycle entry point.
+     *
+     * Called once when the plugin is loaded. This method initializes the configuration
+     * and prepares the native implementation.
+     */
+    override public func load() {
+        // Initialize RankConfig with the correct type
+        let cfg = RankConfig(plugin: self)
+        self.config = cfg
+        implementation.applyConfig(cfg)
+
+        // Log if verbose logging is enabled
+        RankLogger.debug("Rank plugin loaded.")
+    }
+
+    // MARK: - Error Mapping
+
+    /**
+     * Maps native RankError categories to standardized JS-facing error codes.
+     *
+     * - Parameters:
+     * - call: The CAPPluginCall to reject.
+     * - error: The native RankError encountered during execution.
+     */
+    private func reject(
+        _ call: CAPPluginCall,
+        error: RankError
+    ) {
+        let code: String
+
+        switch error {
+        case .unavailable:
+            code = "UNAVAILABLE"
+        case .permissionDenied:
+            code = "PERMISSION_DENIED"
+        case .initFailed:
+            code = "INIT_FAILED"
+        case .unknownType:
+            code = "UNKNOWN_TYPE"
+        }
+
+        call.reject(error.message, code)
+    }
+
+    // MARK: - Availability
+
+    /**
+     * Checks if the native In-App Review prompt can be displayed on the current device.
+     *
+     * This method verifies if the necessary APIs are available and if the OS version is compatible.
+     * It returns a boolean indicating availability, which can be used by the JavaScript layer to
+     * conditionally show review prompts or fallback UI.
+     *
+     * - Parameter call: CAPPluginCall used to return the availability result.
+     */
+    @objc func isAvailable(_ call: CAPPluginCall) {
+        let available = implementation.isAvailable()
+        call.resolve([
+            "value": available
+        ])
+    }
+
+    // MARK: - Product Page
+
+    /**
+     * Presents the App Store product page within the application.
+     *
+     * This method uses SKStoreProductViewController to display the product page without leaving the app.
+     * It accepts an optional appId parameter, which can override the global configuration.
+     *
+     * - Parameter call: CAPPluginCall containing:
+     * - appId (String, optional): The Apple App ID. Fallbacks to global config.
+     */
+    @objc func presentProductPage(_ call: CAPPluginCall) {
+        guard let appId = call.getString("appId") ?? config?.appleAppId else {
+            call.reject("Apple App ID is missing.", "INIT_FAILED")
+            return
+        }
+
+        implementation.presentProductPage(appId: appId) { success, error in
+            if success {
+                call.resolve()
+            } else {
+                call.reject(error?.localizedDescription ?? "Failed to load product page.", "INIT_FAILED")
+            }
+        }
+    }
+
+    // MARK: - Public Plugin Methods
+
+    /**
+     * Triggers the native iOS In-App Review prompt using SKStoreReviewController.
+     *
+     * This method resolves immediately as iOS does not provide a callback to determine
+     * if the prompt was shown or if the user interacted with it.
+     *
+     * - Parameter call: CAPPluginCall provided by the bridge.
+     */
+    @objc func requestReview(_ call: CAPPluginCall) {
+        // Log the request if verbose logging is enabled
+        RankLogger.debug("Requesting review prompt.")
+
+        // Native iOS SKStoreReviewController logic
+        implementation.requestReview()
+
+        // Always resolve immediately for iOS consistency
+        call.resolve()
+    }
+
+    // MARK: - Store Navigation
+
+    /**
+     * Navigates the user to the App Store page for a specific application.
+     *
+     * - Parameter call: CAPPluginCall containing:
+     * - appId (String, optional): The Apple App ID. Fallbacks to global config.
+     */
+    @objc func openStore(_ call: CAPPluginCall) {
+        // Attempt to retrieve the App ID from call parameters or static configuration
+        guard let appId = call.getString("appId") ?? config?.appleAppId else {
+            call.reject(
+                "Apple App ID is missing. Provide it in config or as a parameter.",
+                "INIT_FAILED"
+            )
+            return
+        }
+
+        RankLogger.debug("Opening App Store for ID: \(appId)")
+        implementation.openStore(appId: appId)
+        call.resolve()
+    }
+
+    /**
+     * Opens a collection page on the App Store.
+     *
+     * This method is not supported on iOS as there is no direct way to link to collections. It will reject with an appropriate message.
+     *
+     * - Parameter call: CAPPluginCall provided by the bridge.
+     */
+    @objc func openCollection(_ call: CAPPluginCall) {
+        call.unavailable("Collections are not supported on iOS.")
+    }
+
+    /**
+     * Opens the App Store page for the specified application ID.
+     *
+     * This method constructs a deep link using the `itms-apps` scheme to direct the user
+     * to the review section of the application's store page.
+     *
+     * - Parameter appId: The numeric Apple App ID (e.g., "123456789").
+     */
+    @objc func openStoreListing(_ call: CAPPluginCall) {
+        guard let appId = call.getString("appId") ?? config?.appleAppId else {
+            call.reject("Apple App ID is missing.", "INIT_FAILED")
+            return
+        }
+        implementation.openStoreListing(appId: appId)
+        call.resolve()
+    }
+
+    // MARK: - Search
+
+    /**
+     * Searches the App Store for the given terms.
+     *
+     * - Parameter call: CAPPluginCall containing:
+     * - terms (String): The search query to find apps or developers.
+     */
+    @objc func search(_ call: CAPPluginCall) {
+        guard let terms = call.getString("terms") else {
+            call.reject("Search terms are missing.")
+            return
+        }
+        implementation.search(terms: terms)
+        call.resolve()
+    }
+
+    // MARK: - Developer Page
+
+    /**
+     * Opens the developer's page on the App Store.
+     *
+     * Since iOS does not have a direct link for developer pages, this method performs a search using the developer's name or ID.
+     *
+     * - Parameter call: CAPPluginCall containing:
+     * - devId (String): The developer identifier or name to search for.
+     */
+    @objc func openDevPage(_ call: CAPPluginCall) {
+        guard let devId = call.getString("devId") else {
+            call.reject("devId is missing.")
+            return
+        }
+        implementation.search(terms: devId) // Fallback on iOS
+        call.resolve()
+    }
+
+    // MARK: - Version
+
+    /**
+     * Retrieves the current native plugin version.
+     *
+     * This version is synchronized from the project's package.json during the build process.
+     *
+     * - Parameter call: CAPPluginCall used to return the version string.
+     */
+    @objc func getPluginVersion(_ call: CAPPluginCall) {
+        // Standardized enum name across all CapKit plugins
+        call.resolve([
+            "version": PluginVersion.number
+        ])
+    }
+}

package/ios/Sources/RankPlugin/Utils/RankLogger.swift

@@ -0,0 +1,69 @@
+import Capacitor
+
+/**
+ Centralized native logger for the Rank plugin.
+
+ Responsibilities:
+ - Provide a single logging entry point
+ - Support runtime-controlled verbose logging
+ - Keep logging behavior consistent across files
+
+ Forbidden:
+ - Controlling application logic
+ - Being queried for flow decisions
+ */
+enum RankLogger {
+
+    /**
+     Controls whether debug logs are printed.
+
+     This value MUST be set once during plugin initialization
+     based on static configuration.
+     */
+    static var verbose: Bool = false
+
+    /**
+     Prints a verbose / debug log message.
+
+     Debug logs are automatically silenced
+     when `verbose` is false.
+     */
+    static func debug(_ items: Any...) {
+        guard verbose else { return }
+        log(items)
+    }
+
+    /**
+     Prints an error log message.
+
+     Error logs are always printed regardless
+     of the verbose flag.
+     */
+    static func error(_ items: Any...) {
+        log(items)
+    }
+}
+
+// MARK: - Internal log printer
+
+/**
+ Low-level log printer with a consistent prefix.
+
+ This function MUST NOT be used outside this file.
+ */
+private func log(
+    _ items: [Any],
+    separator: String = " ",
+    terminator: String = "\n"
+) {
+    CAPLog.print("⚡️ Rank -", terminator: separator)
+
+    for (index, item) in items.enumerated() {
+        CAPLog.print(
+            item,
+            terminator: index == items.count - 1
+                ? terminator
+                : separator
+        )
+    }
+}

package/ios/Sources/RankPlugin/Utils/RankUtils.swift

@@ -0,0 +1,45 @@
+import Foundation
+
+/**
+ Utility helpers for the Rank plugin.
+
+ This type is intentionally empty and serves as a placeholder
+ for future shared helper functions.
+
+ Keeping a dedicated utilities file helps maintain a clean
+ separation between core logic and helper code.
+ */
+struct RankUtils {
+    /**
+     Builds the App Store URL for the given Apple App ID.
+
+     - Parameter appId: The numeric Apple App ID.
+     - Returns: A valid App Store URL for opening the product page or review flow.
+     */
+    static func appStoreURL(appId: String) -> URL? {
+        let urlString = "itms-apps://itunes.apple.com/app/id\(appId)?action=write-review"
+        return URL(string: urlString)
+    }
+
+    /**
+     Builds the App Store search URL for the given search terms.
+
+     - Parameter terms: The search query string.
+     - Returns: A valid App Store URL for performing a search.
+     */
+    static func searchURL(terms: String) -> URL? {
+        let encoded = terms.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? ""
+        return URL(string: "itms-apps://itunes.apple.com/search?term=\(encoded)")
+    }
+
+    /**
+     Builds the App Store URL for a developer page based on the given developer identifier.
+
+     - Parameter devId: The developer identifier or name.
+     - Returns: A valid App Store URL for the developer's page or search results.
+     */
+    static func devPageURL(devId: String) -> URL? {
+        // iOS not have a direct link for DevID, so we use search as fallback
+        return searchURL(terms: devId)
+    }
+}

package/ios/Sources/RankPlugin/Version.swift

@@ -0,0 +1,16 @@
+// This file is automatically generated. Do not modify manually.
+import Foundation
+
+/**
+  Container for the plugin's version information.
+  This enum provides a centralized, single source of truth for the native 
+  version string, synchronized directly from the project's 'package.json'.
+  It ensures parity across JavaScript, Android, and iOS platforms.
+ */
+public enum PluginVersion {
+    /**
+      The semantic version string of the plugin.
+      Value synchronized from package.json: "8.0.0"
+     */
+    public static let number = "8.0.0"
+}

package/ios/Tests/RankPluginTests/RankPluginTests.swift

@@ -0,0 +1,10 @@
+import XCTest
+@testable import Rank
+
+/**
+ Basic functional tests for the Rank plugin native implementation.
+
+ These tests validate the core behavior of the implementation
+ independently from the Capacitor bridge.
+ */
+class RankPluginTests: XCTestCase {}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@cap-kit/rank",
+  "version": "8.0.0",
+  "description": "Unified Capacitor v8 plugin for native In-App Reviews and cross-platform Store navigation.",
+  "type": "module",
+  "private": false,
+  "engines": {
+    "node": ">=24.0.0",
+    "pnpm": ">=10.0.0"
+  },
+  "main": "dist/plugin.cjs.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "unpkg": "dist/plugin.js",
+  "files": [
+    "android/src/main/",
+    "android/build.gradle",
+    "dist/",
+    "ios/Sources",
+    "ios/Tests",
+    "Package.swift",
+    "CapKitRank.podspec",
+    "LICENSE"
+  ],
+  "author": "CapKit Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cap-kit/capacitor-plugins.git",
+    "directory": "packages/rank"
+  },
+  "bugs": {
+    "url": "https://github.com/cap-kit/capacitor-plugins/issues"
+  },
+  "homepage": "https://github.com/cap-kit/capacitor-plugins/tree/main/packages/rank#readme",
+  "keywords": [
+    "capacitor",
+    "capacitor-plugin",
+    "cap-kit",
+    "mobile",
+    "native",
+    "ios",
+    "android",
+    "rank",
+    "market",
+    "review"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@capacitor/cli": "^8.0.2",
+    "@capacitor/android": "^8.0.2",
+    "@capacitor/core": "^8.0.2",
+    "@capacitor/docgen": "^0.3.1",
+    "@capacitor/ios": "^8.0.2",
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "globals": "^17.3.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-java": "^2.8.1",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.57.1",
+    "swiftlint": "^2.0.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": ">=8.0.2"
+  },
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    },
+    "android": {
+      "src": "android"
+    }
+  },
+  "scripts": {
+    "verify": "pnpm run verify:ios && pnpm run verify:android && pnpm run verify:web",
+    "verify:ios": "node ./scripts/sync-version.js && xcodebuild -scheme CapKitRank -destination generic/platform=iOS",
+    "verify:android": "cd android && ./gradlew clean build test && cd ..",
+    "verify:web": "pnpm run build",
+    "lint:android": "cd android && ./gradlew ktlintCheck",
+    "fmt:android": "cd android && ./gradlew ktlintFormat",
+    "lint": "pnpm run eslint . && pnpm run swiftlint lint --strict || true && pnpm run lint:android || true",
+    "format:check": "prettier --check \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java",
+    "format": "eslint --fix . && prettier --write \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java && pnpm run swiftlint --fix --format && pnpm run fmt:android",
+    "eslint": "eslint",
+    "prettier": "prettier \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java",
+    "swiftlint": "node-swiftlint lint ios/Sources",
+    "docgen": "docgen --api RankPlugin --output-readme README.md --output-json dist/docs.json",
+    "build": "node ./scripts/sync-version.js && pnpm run clean && pnpm run docgen && tsc && rollup -c rollup.config.mjs",
+    "clean": "rimraf ./dist",
+    "watch": "tsc --watch",
+    "test": "pnpm run verify",
+    "removePacked": "rimraf -g cap-kit-rank-*.tgz",
+    "publish:locally": "pnpm run removePacked && pnpm run build && pnpm pack"
+  }
+}