@craft-native/android 0.0.89 → 0.0.91

package/README.md

@@ -50,14 +50,14 @@ Build native Android apps with web technologies using Craft.
 
 - **Device Info** - Device model, OS version, screen info
 - **Network Status** - Connection type monitoring (WiFi/Cellular)
-- **App Badge** - Notification badge count
+- **Capability Reporting** - Unsupported app badges are reported honestly
 - **App State** - Foreground/background detection
 - **Flashlight** - Camera flash control
 - **Open URL** - External browser launch
 - **Vibration Pattern** - Custom vibration sequences
 - **App Review** - Google Play In-App Review prompt
 - **Screen Capture** - Take screenshots programmatically
-- **Health/Fitness** - Google Fit integration
+- **Health/Fitness** - Health Connect integration
 
 ## Installation
 
@@ -83,7 +83,7 @@ Replace `app/src/main/assets/index.html` with your web app, or point to a dev se
 ```bash
 craft android build --html-path ../dist/index.html
 # or
-craft android build --dev-server http://192.168.1.100:3456
+craft android build --dev-server http://10.0.2.2:3456
 ```
 
 ### 3. Open in Android Studio
@@ -120,27 +120,32 @@ Edit `craft.config.json` in your Android project:
   "enablePushNotifications": false,
   "enableSecureStorage": true,
   "enableGeolocation": true,
-  "enableClipboard": true,
-  "enableNetworkStatus": true,
-  "enableAppReview": true,
-  "enableFlashlight": true,
-  "enableQRScanner": true,
-  "enableFilePicker": true,
-  "enableFileDownload": true,
-  "enableSocialAuth": true,
-  "enableAudioRecording": true,
-  "enableVideoRecording": true,
-  "enableMotionSensors": true,
-  "enableLocalDatabase": true,
-  "enableBluetooth": true,
-  "enableNFC": true,
-  "enableFitness": false,
-  "enableScreenCapture": true,
-  "minSdk": 24,
-  "targetSdk": 34
+  "enableBackgroundLocation": false,
+  "enableHealthConnect": false,
+  "enableKeepAwake": true,
+  "enableDeepLinks": true,
+  "urlSchemes": ["myapp"],
+  "trustedOrigins": ["https://app.example.com"],
+  "minSdk": 26,
+  "compileSdk": 36,
+  "targetSdk": 35
 }
 ```
 
+Only the fields shown above are generator options. Enabling background location
+also enables foreground geolocation. Push notifications require a regular
+`googleServicesFile` whose JSON contains a client matching the generated
+Android package. Deep links require at least one valid URI scheme; scheme names
+are normalized to lowercase.
+Health Connect normalizes `minSdk` to at least 26 and `compileSdk` to at least 36.
+A custom `appIconPath` must be a regular PNG, WebP, JPG, or GIF file; its supported
+extension is preserved in the generated drawable resource.
+
+Remote app and trusted-origin URLs must use HTTPS. Local development may use
+HTTP with `localhost`, `127.0.0.1`, or the Android emulator host `10.0.2.2`.
+Origins are normalized before they are stored, and a configured development
+server is trusted automatically.
+
 ## JavaScript Bridge
 
 Once Craft is initialized, the `window.craft` object is available:
@@ -215,18 +220,19 @@ await window.craft.db.execute('CREATE TABLE users (id INTEGER PRIMARY KEY, name
 await window.craft.db.execute('INSERT INTO users (name) VALUES (?)', ['Alice']);
 const users = await window.craft.db.query('SELECT * FROM users');
 
-// Bluetooth LE Scanning
-window.craft.startBluetoothScan();
+// Bluetooth LE Scanning. Rejects when the device has no adapter, Bluetooth is
+// switched off, permission is denied, or the platform scanner cannot start.
+await window.craft.bluetooth.startScan();
 window.addEventListener('craftBluetoothDevice', (e) => {
   console.log(e.detail.name, e.detail.address, e.detail.rssi);
 });
-window.craft.stopBluetoothScan();
+window.craft.bluetooth.stopScan();
 
 // NFC Tag Reading
 const nfcData = await window.craft.scanNFC();
 console.log(nfcData); // Tag content
 
-// Health/Fitness (Google Fit)
+// Health/Fitness (Health Connect)
 await window.craft.requestFitnessAuthorization();
 const steps = await window.craft.getFitnessData('steps', startDate, endDate);
 
@@ -270,9 +276,10 @@ const text = await window.craft.clipboard.read();
 const device = window.craft.getDeviceInfo();
 console.log(device.model, device.manufacturer, device.systemVersion);
 
-// App Badge
-window.craft.setBadge(5);
-window.craft.clearBadge();
+// App badges have no portable Android API, so this is always false.
+if (window.craft.capabilities.appBadge) {
+  window.craft.setBadge(5);
+}
 
 // Network Status
 const network = window.craft.getNetworkStatus();
@@ -369,15 +376,17 @@ window.craft.unlockOrientation();           // Allow all orientations
 
 // ==================== Medium Value Bridges ====================
 
-// Background Tasks (WorkManager)
-await window.craft.backgroundTask.register('sync-data');
-await window.craft.backgroundTask.schedule('sync-data', {
-  delay: 900,              // 15 minutes
-  requiresNetwork: true,
-  requiresCharging: false
-});
-await window.craft.backgroundTask.cancel('sync-data');
-await window.craft.backgroundTask.cancelAll();
+// Background Tasks are not implemented on Android. These methods reject
+// instead of reporting that work was scheduled when no worker can run.
+try {
+  await window.craft.backgroundTask.schedule('sync-data', {
+    delay: 900,
+    requiresNetwork: true,
+    requiresCharging: false
+  });
+} catch (error) {
+  console.error(error);
+}
 
 // PDF Viewer (opens in external PDF app)
 await window.craft.openPDF('https://example.com/document.pdf');
@@ -453,16 +462,10 @@ await window.craft.widget.reload();
 
 // ==================== Google Assistant (App Actions) ====================
 
-// Note: App Actions are defined in shortcuts.xml, not dynamically
-// This stores action handlers for incoming intents
-await window.craft.siri.register('Open my app', 'open*app');
-
-// Remove a voice action
-await window.craft.siri.remove('open*app');
-
-// Listen for voice assistant invocations
-window.craft.siri.onInvoke((detail) => {
-  console.log('Voice action:', detail.action);
+// App Actions are declared statically in app/src/main/res/xml/shortcuts.xml.
+// Listen for incoming Google Assistant intents forwarded by the bridge.
+window.addEventListener('craftVoiceAction', (event) => {
+  console.log('Voice action:', event.detail.action);
 });
 
 // ==================== Wear OS Connectivity ====================
@@ -516,54 +519,58 @@ Options:
 
 - Android Studio with Android SDK
 - JDK 17+
-- Gradle 8.4+
+- Gradle 8.11.1 (the generator creates a wrapper pinned to this version)
 - ADB (for device deployment)
 
 ## Permissions
 
-Add to your AndroidManifest.xml as needed:
-
-```xml
-<!-- Speech Recognition -->
-<uses-permission android:name="android.permission.RECORD*AUDIO" />
-
-<!-- Camera -->
-<uses-permission android:name="android.permission.CAMERA" />
-<uses-permission android:name="android.permission.WRITE*EXTERNAL*STORAGE" />
+The generator adds manifest permissions from enabled capabilities:
+
+| Option | Android permissions |
+| --- | --- |
+| `enableSpeechRecognition` | `RECORD_AUDIO` |
+| `enableCamera` | `CAMERA` |
+| `enableHaptics` | `VIBRATE` |
+| `enableBiometric` | `USE_BIOMETRIC` |
+| `enableGeolocation` | `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION` |
+| `enableBackgroundLocation` | foreground location plus `ACCESS_BACKGROUND_LOCATION` and foreground-service permissions |
+| `enablePushNotifications` | `POST_NOTIFICATIONS` |
+| `enableKeepAwake` | `WAKE_LOCK` |
+| `enableHealthConnect` | the configured Health Connect read/write permissions |
+
+Use `permissions.check('location')` and `permissions.request('location')` from
+`craft-native/mobile` for runtime authorization. Android precise and
+approximate access both count as a granted foreground location permission;
+foreground fixes, watches, and recording accept either grant, with accuracy
+controlled by Android. Obtaining a fix is still a separate operation. See the
+[Permissions API](../../docs/api/mobile/permissions.md) for status semantics.
+
+## Promise Lifecycle and Concurrency
+
+Promise-based bridge calls have one active request slot per native callback
+channel. A second request on the same channel rejects immediately with an
+`already in progress` error, without replacing the first request's callbacks.
+Calls on different channels can run concurrently. Some related methods share a
+channel—for example, shortcut mutations serialize with other shortcut
+mutations—so callers should await one before starting the next.
+
+Native success, error, cancellation, and timeout callbacks settle a request at
+most once. Synchronous JavaScript-interface failures are converted to Promise
+rejections. Permission requests use request IDs and a 30-second timeout, while
+one-shot location requests use a 15-second timeout. Destroying the bridge
+rejects all pending work and any new request, while callbacks queued by the old
+Activity lifecycle are ignored. Reinjecting the bridge rejects old work and
+opens a fresh runtime.
+
+## Template Validation
+
+Android projects generated with the default and capability-heavy configurations
+are assembled in CI, and their Kotlin permission tests are run. Contributors
+with JDK 17, Android SDK 36, and Gradle 8.11.1 installed can run the same check:
 
-<!-- Location -->
-<uses-permission android:name="android.permission.ACCESS*FINE*LOCATION" />
-<uses-permission android:name="android.permission.ACCESS*COARSE*LOCATION" />
-
-<!-- Biometric -->
-<uses-permission android:name="android.permission.USE*BIOMETRIC" />
-
-<!-- Vibration -->
-<uses-permission android:name="android.permission.VIBRATE" />
-
-<!-- NFC -->
-<uses-permission android:name="android.permission.NFC" />
-<uses-feature android:name="android.hardware.nfc" android:required="false" />
-
-<!-- Bluetooth -->
-<uses-permission android:name="android.permission.BLUETOOTH" />
-<uses-permission android:name="android.permission.BLUETOOTH*ADMIN" />
-<uses-permission android:name="android.permission.BLUETOOTH*SCAN" />
-<uses-permission android:name="android.permission.BLUETOOTH*CONNECT" />
-
-<!-- Fitness (Google Fit) -->
-<uses-permission android:name="android.permission.ACTIVITY*RECOGNITION" />
-
-<!-- Contacts -->
-<uses-permission android:name="android.permission.READ*CONTACTS" />
-<uses-permission android:name="android.permission.WRITE*CONTACTS" />
-
-<!-- Calendar -->
-<uses-permission android:name="android.permission.READ*CALENDAR" />
-<uses-permission android:name="android.permission.WRITE*CALENDAR" />
-
-<!-- Notifications (Android 13+) -->
-<uses-permission android:name="android.permission.POST*NOTIFICATIONS" />
+```bash
+cd packages/android
+bun run test:templates
 ```
 
 ## Development Mode
@@ -574,14 +581,16 @@ For hot-reload during development:
 # Terminal 1: Start your dev server
 bun run dev  # e.g., http://localhost:3456
 
-# Terminal 2: Build Android with dev server (use your Mac's IP)
-craft android build --dev-server http://192.168.1.100:3456
+# Terminal 2: Build for an Android emulator
+craft android build --dev-server http://10.0.2.2:3456
 
 # Open in Android Studio and run on device
 craft android open
 ```
 
-The app will load from your dev server instead of bundled HTML.
+The emulator resolves `10.0.2.2` to the host machine. For a physical device,
+use an HTTPS development endpoint. The app will load from that server instead
+of bundled HTML.
 
 ## Publishing
 
@@ -597,6 +606,7 @@ This will:
 2. Output path for manual upload to Play Console
 
 For automated uploads, integrate with fastlane:
+
 ```bash
 fastlane supply --aab ./android/app/build/outputs/bundle/release/app-release.aab
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/android",
-  "version": "0.0.89",
+  "version": "0.0.91",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/android#readme",
   "repository": {
     "type": "git",
@@ -19,7 +19,9 @@
     }
   },
   "scripts": {
-    "build": "bun build.ts"
+    "build": "bun build.ts",
+    "test": "bun test",
+    "test:templates": "bun scripts/compile-templates.ts"
   },
   "files": [
     "dist",