capacitor-environment-checker 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-20
+- Initial public release.
+- Added isTestFlight() API with typed response.
+- Implemented iOS TestFlight detection via sandboxReceipt heuristic.
+- Added deterministic safe fallback for Android and Web (always false).
+- Added lint/build/test CI workflow.

package/CapacitorEnvironmentChecker.podspec

@@ -0,0 +1,13 @@
+Pod::Spec.new do |s|
+  s.name = 'CapacitorEnvironmentChecker'
+  s.version = '0.1.0'
+  s.summary = 'Capacitor plugin to detect whether an iOS app is running via TestFlight.'
+  s.license = 'MIT'
+  s.homepage = 'https://github.com/guidg/capacitor-environment-checker'
+  s.author = { 'guidg' => 'guidg@users.noreply.github.com' }
+  s.source = { :git => 'https://github.com/guidg/capacitor-environment-checker.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '13.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guidg
+
+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/Package.swift

@@ -0,0 +1,27 @@
+// swift-tools-version:5.9
+import PackageDescription
+
+let package = Package(
+    name: "EnvironmentCheckerPlugin",
+    platforms: [.iOS(.v13)],
+    products: [
+        .library(name: "EnvironmentCheckerPlugin", targets: ["EnvironmentCheckerPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "6.0.0")
+    ],
+    targets: [
+        .target(
+            name: "EnvironmentCheckerPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/EnvironmentCheckerPlugin"
+        ),
+        .testTarget(
+            name: "EnvironmentCheckerPluginTests",
+            dependencies: ["EnvironmentCheckerPlugin"],
+            path: "ios/Tests/EnvironmentCheckerPluginTests"
+        )
+    ]
+)

package/README.md

@@ -0,0 +1,58 @@
+# capacitor-environment-checker
+
+Capacitor plugin to detect whether an iOS app is running via TestFlight, with safe fallbacks for Android and Web.
+
+## Install
+
+```bash
+npm i capacitor-environment-checker
+npx cap sync
+```
+
+## Usage
+
+```ts
+import EnvironmentChecker from 'capacitor-environment-checker';
+
+const { isTestFlight } = await EnvironmentChecker.isTestFlight();
+console.log('isTestFlight:', isTestFlight);
+```
+
+## API
+
+### isTestFlight()
+
+```ts
+isTestFlight(): Promise<{ isTestFlight: boolean }>;
+```
+
+Returns whether the app is running via TestFlight.
+
+## Platform behavior
+
+- iOS: uses sandbox receipt heuristic (`sandboxReceipt`) to infer TestFlight.
+- Android: always returns `false` in v0.1.0.
+- Web: always returns `false` in v0.1.0.
+
+## Why Android/Web return false
+
+`isTestFlight` is an iOS-specific concept. For v0.1.0, Android and Web are deterministic fallbacks to keep cross-platform code safe and predictable.
+
+## Troubleshooting
+
+- Method not found after install:
+	- Run `npx cap sync`.
+	- Rebuild native projects.
+- iOS unexpected value:
+	- Validate whether app receipt is sandbox receipt.
+	- Ensure you are testing through the intended distribution flow.
+
+## Compatibility
+
+- Capacitor: `6+`
+- TypeScript: supported
+
+## Notes
+
+- This plugin does not collect personal data.
+- This plugin does not call external services.

package/android/build.gradle

@@ -0,0 +1,30 @@
+apply plugin: 'com.android.library'
+
+android {
+    namespace "com.guidg.environmentchecker"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 22
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+        versionCode 1
+        versionName "0.1"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    lintOptions {
+        abortOnError false
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    testImplementation "junit:junit:4.13.2"
+    androidTestImplementation "androidx.test.ext:junit:1.2.1"
+    androidTestImplementation "androidx.test.espresso:espresso-core:3.6.1"
+}

package/android/src/main/java/com/guidg/environmentchecker/EnvironmentCheckerPlugin.kt

@@ -0,0 +1,17 @@
+package com.guidg.environmentchecker
+
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+
+@CapacitorPlugin(name = "EnvironmentChecker")
+class EnvironmentCheckerPlugin : Plugin() {
+    @PluginMethod
+    fun isTestFlight(call: PluginCall) {
+        val result = JSObject()
+        result.put("isTestFlight", false)
+        call.resolve(result)
+    }
+}

package/dist/definitions.d.ts

@@ -0,0 +1,7 @@
+export interface IsTestFlightResult {
+    isTestFlight: boolean;
+}
+export interface EnvironmentCheckerPlugin {
+    isTestFlight(): Promise<IsTestFlightResult>;
+}
+//# sourceMappingURL=definitions.d.ts.map

package/dist/definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC7C"}

package/dist/definitions.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { EnvironmentCheckerPlugin } from './definitions';
+declare const EnvironmentChecker: EnvironmentCheckerPlugin;
+export * from './definitions';
+export { EnvironmentChecker };
+export default EnvironmentChecker;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAE9D,QAAA,MAAM,kBAAkB,0BAEtB,CAAC;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,eAAe,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+import { registerPlugin } from '@capacitor/core';
+const EnvironmentChecker = registerPlugin('EnvironmentChecker', {
+    web: () => import('./web').then((m) => new m.EnvironmentCheckerWeb()),
+});
+export * from './definitions';
+export { EnvironmentChecker };
+export default EnvironmentChecker;

package/dist/web.d.ts

@@ -0,0 +1,6 @@
+import { WebPlugin } from '@capacitor/core';
+import type { EnvironmentCheckerPlugin, IsTestFlightResult } from './definitions';
+export declare class EnvironmentCheckerWeb extends WebPlugin implements EnvironmentCheckerPlugin {
+    isTestFlight(): Promise<IsTestFlightResult>;
+}
+//# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAElF,qBAAa,qBAAsB,SAAQ,SAAU,YAAW,wBAAwB;IAChF,YAAY,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAGlD"}

package/dist/web.js

@@ -0,0 +1,6 @@
+import { WebPlugin } from '@capacitor/core';
+export class EnvironmentCheckerWeb extends WebPlugin {
+    async isTestFlight() {
+        return { isTestFlight: false };
+    }
+}

package/ios/Sources/EnvironmentCheckerPlugin/EnvironmentCheckerPlugin.swift

@@ -0,0 +1,16 @@
+import Capacitor
+import Foundation
+
+@objc(EnvironmentCheckerPlugin)
+public class EnvironmentCheckerPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "EnvironmentCheckerPlugin"
+    public let jsName = "EnvironmentChecker"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "isTestFlight", returnType: CAPPluginReturnPromise)
+    ]
+
+    @objc public func isTestFlight(_ call: CAPPluginCall) {
+        let isTestFlight = Bundle.main.appStoreReceiptURL?.lastPathComponent == "sandboxReceipt"
+        call.resolve(["isTestFlight": isTestFlight])
+    }
+}

package/ios/Tests/EnvironmentCheckerPluginTests/EnvironmentCheckerPluginTests.swift

@@ -0,0 +1,8 @@
+import XCTest
+@testable import EnvironmentCheckerPlugin
+
+final class EnvironmentCheckerPluginTests: XCTestCase {
+    func testModuleLoads() {
+        XCTAssertTrue(true)
+    }
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "capacitor-environment-checker",
+  "version": "0.1.0",
+  "description": "Capacitor plugin to detect whether an iOS app is running via TestFlight, with safe fallbacks for Android and Web.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "android/src/main/",
+    "android/build.gradle",
+    "dist/",
+    "ios/Sources/",
+    "ios/Tests/",
+    "Package.swift",
+    "CapacitorEnvironmentChecker.podspec",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "capacitor",
+    "capacitor-plugin",
+    "ios",
+    "testflight"
+  ],
+  "author": "guidg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guidg/capacitor-environment-checker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/guidg/capacitor-environment-checker/issues"
+  },
+  "homepage": "https://github.com/guidg/capacitor-environment-checker#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "vitest run",
+    "verify": "npm run lint && npm run build && npm run test"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^6.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.23.0",
+    "@capacitor/android": "^6.2.0",
+    "@capacitor/core": "^6.2.0",
+    "@capacitor/ios": "^6.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.30.1",
+    "@typescript-eslint/parser": "^8.30.1",
+    "eslint": "^9.23.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  },
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    },
+    "android": {
+      "src": "android"
+    }
+  }
+}