@cap-kit/settings 8.0.0-next.0

package/ios/Sources/SettingsPlugin/SettingsImpl.swift

@@ -0,0 +1,84 @@
+import Foundation
+import UIKit
+
+/**
+ Native iOS implementation for the Settings plugin.
+
+ This class contains ONLY platform logic and must not:
+ - access CAPPluginCall
+ - depend on Capacitor
+ - contain JavaScript or bridge-related logic
+
+ Mapping from JavaScript-facing options to platform-specific
+ settings URLs is delegated to SettingsUtils.
+ */
+@objc public final class SettingsImpl: NSObject {
+
+    // Properties
+    private var config: SettingsConfig?
+
+    // Initializer
+    override init() {
+        super.init()
+    }
+
+    // MARK: - Result
+
+    struct Result {
+        let success: Bool
+        let error: String?
+        let code: String?
+    }
+
+    // MARK: - Configuration
+
+    /**
+     Applies the plugin configuration.
+
+     This method should be called exactly once during plugin initialization.
+     Its responsibility is to translate configuration values into runtime
+     behavior (e.g. enabling verbose logging).
+     */
+    func applyConfig(_ config: SettingsConfig) {
+        self.config = config
+        SettingsLogger.verbose = config.verboseLogging
+        SettingsLogger.debug("Configuration applied. Verbose logging:", "\(config.verboseLogging)")
+    }
+
+    // MARK: - Settings
+
+    /**
+     Opens the requested iOS settings page.
+
+     - Parameter option: The settings option to open.
+
+     - Returns:
+     - success: Indicates whether the URL was valid and dispatched.
+     - error: Optional human-readable error.
+     - code: Optional machine-readable error code.
+     */
+    func open(option: String?) -> Result {
+        guard let url = SettingsUtils.resolveSettingsURL(for: option) else {
+            return Result(
+                success: false,
+                error: "Requested setting is not available on iOS",
+                code: "UNAVAILABLE"
+            )
+        }
+
+        guard UIApplication.shared.canOpenURL(url) else {
+            SettingsLogger.debug("Cannot open URL:", url.absoluteString)
+            return Result(
+                success: false,
+                error: "Cannot open settings URL",
+                code: "UNAVAILABLE"
+            )
+        }
+
+        DispatchQueue.main.async(execute: DispatchWorkItem {
+            UIApplication.shared.open(url, options: [:])
+        })
+
+        return Result(success: true, error: nil, code: nil)
+    }
+}

package/ios/Sources/SettingsPlugin/SettingsPlugin.swift

@@ -0,0 +1,103 @@
+import Foundation
+import Capacitor
+
+/**
+ Capacitor bridge for the Settings plugin.
+
+ This file MUST:
+ - read input from CAPPluginCall
+ - delegate logic to SettingsImpl
+ - resolve calls using state-based results
+ */
+@objc(SettingsPlugin)
+public final class SettingsPlugin: CAPPlugin, CAPBridgedPlugin {
+
+    // Configuration instance
+    private var config: SettingsConfig?
+
+    /// An instance of the implementation class that contains the plugin's core functionality.
+    private let implementation = SettingsImpl()
+
+    /// The unique identifier for the plugin.
+    public let identifier = "SettingsPlugin"
+
+    /// The name used to reference this plugin in JavaScript.
+    public let jsName = "Settings"
+
+    /**
+     A list of methods exposed by this plugin. These methods can be called from the JavaScript side.
+     - `open`: A method that opens a specified iOS settings page.
+     - `openIOS`: An alias for the `open` method, specifically for iOS
+     - `getPluginVersion`: A method that returns the version of the plugin.
+     */
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "open", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "openIOS", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getPluginVersion", returnType: CAPPluginReturnPromise)
+    ]
+
+    /**
+     Plugin lifecycle entry point.
+
+     Called once when the plugin is loaded by the Capacitor bridge.
+     This is the correct place to:
+     - read configuration values
+     - initialize native resources
+     - configure the implementation instance
+     */
+    override public func load() {
+        // Initialize SettingsConfig with the correct type
+        let cfg = SettingsConfig(plugin: self)
+        self.config = cfg
+        implementation.applyConfig(cfg)
+
+        // Log if verbose logging is enabled
+        SettingsLogger.debug("Settings plugin loaded with config:", cfg)
+    }
+
+    // MARK: - Settings
+
+    /// Opens the requested iOS settings page.
+    @objc func open(_ call: CAPPluginCall) {
+        resolveOpenResult(call, option: call.getString("optionIOS", ""))
+    }
+
+    /// Opens the requested iOS settings page.
+    @objc func openIOS(_ call: CAPPluginCall) {
+        resolveOpenResult(call, option: call.getString("option", ""))
+    }
+
+    // MARK: - Version
+
+    /// Retrieves the plugin version synchronized from package.json.
+    @objc func getPluginVersion(_ call: CAPPluginCall) {
+        // Standardized enum name across all CapKit plugins
+        call.resolve([
+            "version": PluginVersion.number
+        ])
+    }
+
+    // MARK: - Helpers
+
+    /// Resolves the result of an open settings call.
+    private func resolveOpenResult(
+        _ call: CAPPluginCall,
+        option: String
+    ) {
+        let result = implementation.open(option: option)
+
+        var payload: [String: Any] = [
+            "success": result.success
+        ]
+
+        if let error = result.error {
+            payload["error"] = error
+        }
+
+        if let code = result.code {
+            payload["code"] = code
+        }
+
+        call.resolve(payload)
+    }
+}

package/ios/Sources/SettingsPlugin/Utils/SettingsLogger.swift

@@ -0,0 +1,57 @@
+import Capacitor
+
+/**
+ Centralized logger for the Settings plugin.
+
+ This logger mirrors the Android Logger pattern and provides:
+ - a single logging entry point
+ - runtime-controlled verbose logging
+ - consistent log formatting
+
+ Business logic MUST NOT perform configuration checks directly.
+ */
+enum SettingsLogger {
+
+    /**
+     Controls whether debug logs are printed.
+
+     This value is set once during plugin load
+     based on configuration values.
+     */
+    static var verbose: Bool = false
+
+    /**
+     Prints a verbose / debug log message.
+
+     This method is intended for development-time diagnostics
+     and is automatically silenced when verbose logging is disabled.
+     */
+    static func debug(_ items: Any...) {
+        guard verbose else { return }
+        log(items)
+    }
+
+    /**
+     Prints an error log message.
+
+     Error logs are always printed regardless of verbosity.
+     */
+    static func error(_ items: Any...) {
+        log(items)
+    }
+}
+
+/**
+ Low-level log printer with a consistent prefix.
+
+ This function should not be used directly outside this file.
+ */
+private func log(_ items: Any..., separator: String = " ", terminator: String = "\n") {
+    CAPLog.print("⚡️  Settings -", terminator: separator)
+    for (itemIndex, item) in items.enumerated() {
+        CAPLog.print(
+            item,
+            terminator: itemIndex == items.count - 1 ? terminator : separator
+        )
+    }
+}

package/ios/Sources/SettingsPlugin/Utils/SettingsUtils.swift

@@ -0,0 +1,70 @@
+import Foundation
+import UIKit
+
+/**
+ Utility helpers for resolving iOS Settings URLs.
+
+ This type contains ONLY mapping logic and must not:
+ - interact with Capacitor
+ - open URLs
+ - perform side effects
+ */
+enum SettingsUtils {
+
+    static func resolveSettingsURL(for option: String?) -> URL? {
+        guard let option else {
+            return nil
+        }
+
+        let settingsPaths: [String: String] = [
+            "about": "App-prefs:General&path=About",
+            "autoLock": "App-prefs:General&path=AUTOLOCK",
+            "bluetooth": "App-prefs:Bluetooth",
+            "dateTime": "App-prefs:General&path=DATE_AND_TIME",
+            "facetime": "App-prefs:FACETIME",
+            "general": "App-prefs:General",
+            "keyboard": "App-prefs:General&path=Keyboard",
+            "iCloud": "App-prefs:CASTLE",
+            "iCloudStorageBackup": "App-prefs:CASTLE&path=STORAGE_AND_BACKUP",
+            "international": "App-prefs:General&path=INTERNATIONAL",
+            "locationServices": "App-prefs:Privacy&path=LOCATION",
+            "music": "App-prefs:MUSIC",
+            "notes": "App-prefs:NOTES",
+            "notifications": "App-prefs:NOTIFICATIONS_ID",
+            "phone": "App-prefs:Phone",
+            "photos": "App-prefs:Photos",
+            "managedConfigurationList": "App-prefs:General&path=ManagedConfigurationList",
+            "reset": "App-prefs:General&path=Reset",
+            "ringtone": "App-prefs:Sounds&path=Ringtone",
+            "sounds": "App-prefs:Sounds",
+            "softwareUpdate": "App-prefs:General&path=SOFTWARE_UPDATE_LINK",
+            "store": "App-prefs:STORE",
+            "tracking": "App-prefs:Privacy&path=USER_TRACKING",
+            "wallpaper": "App-prefs:Wallpaper",
+            "wifi": "App-prefs:WIFI",
+            "tethering": "App-prefs:INTERNET_TETHERING",
+            "doNotDisturb": "App-prefs:DO_NOT_DISTURB",
+            "touchIdPasscode": "App-prefs:TOUCHID_PASSCODE",
+            "screenTime": "App-prefs:SCREEN_TIME",
+            "accessibility": "App-prefs:ACCESSIBILITY",
+            "vpn": "App-prefs:VPN"
+        ]
+
+        if let path = settingsPaths[option] {
+            return URL(string: path)
+        }
+
+        if option == "app" {
+            return URL(string: UIApplication.openSettingsURLString)
+        }
+
+        if option == "appNotification" {
+            if #available(iOS 16.0, *) {
+                return URL(string: UIApplication.openNotificationSettingsURLString)
+            }
+            return URL(string: UIApplication.openSettingsURLString)
+        }
+
+        return nil
+    }
+}

package/ios/Sources/SettingsPlugin/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-next.0"
+     */
+    public static let number = "8.0.0-next.0"
+}

package/ios/Tests/SettingsPluginTests/SettingsPluginTests.swift

@@ -0,0 +1,21 @@
+import XCTest
+@testable import Settings
+
+/**
+ Basic functional tests for the Settings plugin native implementation.
+
+ These tests validate the core behavior of the implementation
+ independently from the Capacitor bridge.
+ */
+class SettingsPluginTests: XCTestCase {
+    func testEcho() {
+        // This is an example of a functional test case for a plugin.
+        // Use XCTAssert and related functions to verify your tests produce the correct results.
+
+        let implementation = SettingsImpl()
+        let value = "Hello, World!"
+        let result = implementation.echo(value)
+
+        XCTAssertEqual(value, result)
+    }
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@cap-kit/settings",
+  "version": "8.0.0-next.0",
+  "description": "Capacitor plugin to open app and system settings on iOS and Android.",
+  "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",
+    "CapKitSettings.podspec",
+    "LICENSE"
+  ],
+  "author": "CapKit Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cap-kit/capacitor-plugins.git",
+    "directory": "packages/settings"
+  },
+  "bugs": {
+    "url": "https://github.com/cap-kit/capacitor-plugins/issues"
+  },
+  "homepage": "https://github.com/cap-kit/capacitor-plugins/tree/main/packages/settings#readme",
+  "keywords": [
+    "capacitor",
+    "capacitor-plugin",
+    "plugin",
+    "native",
+    "settings",
+    "cap-kit"
+  ],
+  "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.2.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-java": "^2.8.1",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.57.0",
+    "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 CapKitSettings -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 SettingsPlugin --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-settings-*.tgz",
+    "publish:locally": "pnpm run removePacked && pnpm run build && pnpm pack"
+  }
+}