expo-app-blocker 0.1.61 → 0.1.63

package/README.md

@@ -388,6 +388,31 @@ startMonitoring();   // Start foreground service (auto-started on init)
 stopMonitoring();    // Stop monitoring
 ```
 
+#### Deep-link contract (how your app is launched)
+
+When the foreground service detects a blocked app, it brings **your** app to the
+front via a deep link using your app's own URL scheme:
+
+```
+<yourScheme>://blocked?app=<AppName>&package=<package.name>&reason=<reason>
+```
+
+| Param | Description |
+|---|---|
+| `app` | Human-readable label of the blocked app (URL-encoded), e.g. `Instagram` |
+| `package` | Android package name of the blocked app, e.g. `com.instagram.android` |
+| `reason` | Why the block fired — see below. Lets you branch your UI |
+
+`reason` values:
+
+| Value | Meaning |
+|---|---|
+| `opened` | A blocked app was freshly brought to the foreground. |
+| `expired` | A [temporary unlock](#android-temporary-unlock) expired while the user was still **inside** the blocked app. Handle this if you want a softer "time's up" interstitial instead of jumping straight into your gate. |
+
+Handle the deep link with `expo-linking` / `expo-router` like any other route.
+Your scheme is auto-detected from the app config; no extra setup required.
+
 ### iOS: App Selection
 
 Two ways to let users pick which apps to block:
@@ -480,6 +505,37 @@ const seconds = getRemainingUnlockTime(); // seconds remaining
 await relockApps();                        // re-lock immediately
 ```
 
+### Android: Temporary Unlock
+
+The same temporary-unlock API works on Android. The foreground service pauses
+blocking for the requested duration and auto-resumes when it expires — the timer
+lives in the service, so it survives your app being backgrounded.
+
+```typescript
+import {
+  temporaryUnlock,
+  getRemainingUnlockTime,
+  relockApps,
+} from 'expo-app-blocker';
+
+// Suppress blocking for N minutes; auto-resumes on expiry
+await temporaryUnlock(15);
+// { unlocked: true, expiresAt: number }
+
+const seconds = getRemainingUnlockTime(); // seconds remaining, 0 if none
+await relockApps();                        // end the unlock now, re-block immediately
+```
+
+| Function | Android behavior |
+|---|---|
+| `temporaryUnlock(minutes)` | Suppresses blocking for `minutes` (min 1, rounded). Replaces any active unlock. |
+| `getRemainingUnlockTime()` | Seconds left on the active unlock, or `0`. Backed by a persisted expiry, so it's accurate without the app holding service state. |
+| `relockApps()` | Ends the unlock immediately and re-blocks the foreground app on the next poll. |
+| `isTemporarilyUnlocked()` | iOS only — returns `false` on Android. Use `getRemainingUnlockTime() > 0` instead. |
+
+> When an unlock expires while the user is still inside a blocked app, the
+> deep link fires with `reason=expired` (see [Deep-link contract](#deep-link-contract-how-your-app-is-launched)).
+
 ### iOS: Shield Button Events
 
 When a user taps the primary button on the shield overlay, your app receives an event:

package/android/src/main/java/expo/modules/appblocker/AppBlockerService.kt

@@ -22,12 +22,23 @@ class AppBlockerService : Service() {
   private var lastForegroundPackage: String? = null
   private lateinit var overlayManager: OverlayManager
   private val unlockController by lazy { TemporaryUnlockController(this, handler) }
+  private var wasUnlocked = false
 
   private val pollRunnable = object : Runnable {
     override fun run() {
-      if (!unlockController.isUnlocked) {
+      if (unlockController.isUnlocked) {
+        wasUnlocked = true
+      } else {
         val foregroundPackage = getCurrentForegroundPackage()
-        if (foregroundPackage != null && foregroundPackage != lastForegroundPackage) {
+        val unlockJustExpired = wasUnlocked
+        wasUnlocked = false
+
+        if (unlockJustExpired && foregroundPackage != null && isBlocked(foregroundPackage)) {
+          // Earned time ran out while the user was still inside a blocked app.
+          Log.d(TAG, "Unlock expired in foreground app: $foregroundPackage")
+          lastForegroundPackage = foregroundPackage
+          block(foregroundPackage, BlockReason.EXPIRED)
+        } else if (foregroundPackage != null && foregroundPackage != lastForegroundPackage) {
           Log.d(TAG, "Foreground changed: $foregroundPackage")
           lastForegroundPackage = foregroundPackage
           handleForegroundChange(foregroundPackage)
@@ -48,18 +59,24 @@ class AppBlockerService : Service() {
     handler.post(pollRunnable)
   }
 
+  private fun isBlocked(packageName: String): Boolean =
+    packageName in AppBlockerPrefs.getBlockedPackages(this)
+
   private fun handleForegroundChange(foregroundPackage: String) {
-    val blocked = AppBlockerPrefs.getBlockedPackages(this)
-    if (foregroundPackage in blocked) {
+    if (isBlocked(foregroundPackage)) {
       Log.d(TAG, "Blocked app in foreground: $foregroundPackage")
-      overlayManager.show(foregroundPackage)
-      showBlockedNotification(foregroundPackage)
+      block(foregroundPackage, BlockReason.OPENED)
     } else {
       overlayManager.hide()
     }
   }
 
-  private fun showBlockedNotification(packageName: String) {
+  private fun block(packageName: String, reason: BlockReason) {
+    overlayManager.show(packageName, reason)
+    showBlockedNotification(packageName, reason)
+  }
+
+  private fun showBlockedNotification(packageName: String, reason: BlockReason) {
     val appName = try {
       val pm = this.packageManager
       val appInfo = pm.getApplicationInfo(packageName, 0)
@@ -74,7 +91,10 @@ class AppBlockerService : Service() {
     val scheme = getAppScheme()
     val deepLinkIntent = Intent(
       Intent.ACTION_VIEW,
-      Uri.parse("${scheme}://blocked?app=${Uri.encode(appName)}&package=${Uri.encode(packageName)}")
+      Uri.parse(
+        "${scheme}://blocked?app=${Uri.encode(appName)}" +
+          "&package=${Uri.encode(packageName)}&reason=${reason.slug}"
+      )
     ).apply {
       addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
     }

package/android/src/main/java/expo/modules/appblocker/BlockReason.kt

@@ -0,0 +1,14 @@
+package expo.modules.appblocker
+
+/**
+ * Why a blocked app is being intercepted right now. Carried into the deep link
+ * so the JS side can branch (e.g. a softer "time's up" interstitial when an
+ * earned-time window expires while the user is still inside the app).
+ */
+enum class BlockReason(val slug: String) {
+  /** A blocked app was freshly brought to the foreground. */
+  OPENED("opened"),
+
+  /** A temporary unlock expired while a blocked app was already in the foreground. */
+  EXPIRED("expired"),
+}

package/android/src/main/java/expo/modules/appblocker/OverlayManager.kt

@@ -24,11 +24,11 @@ class OverlayManager(private val context: Context) {
 
   private var overlayView: View? = null
 
-  fun show(blockedPackageName: String? = null) {
+  fun show(blockedPackageName: String? = null, reason: BlockReason = BlockReason.OPENED) {
     if (overlayView != null) {
       Log.d(TAG, "Overlay already visible")
       if (blockedPackageName != null) {
-        navigateToApp(blockedPackageName)
+        navigateToApp(blockedPackageName, reason)
       } else {
         bringAppToFront()
       }
@@ -47,7 +47,7 @@ class OverlayManager(private val context: Context) {
     }
 
     if (blockedPackageName != null) {
-      navigateToApp(blockedPackageName)
+      navigateToApp(blockedPackageName, reason)
     } else {
       bringAppToFront()
     }
@@ -72,14 +72,17 @@ class OverlayManager(private val context: Context) {
     packageName
   }
 
-  private fun navigateToApp(blockedPackageName: String) {
+  private fun navigateToApp(blockedPackageName: String, reason: BlockReason) {
     val appName = resolveAppName(blockedPackageName)
 
     // Use the app's own scheme for deep linking
     val scheme = getAppScheme()
     val deepLinkIntent = Intent(
       Intent.ACTION_VIEW,
-      Uri.parse("${scheme}://blocked?app=${Uri.encode(appName)}&package=${Uri.encode(blockedPackageName)}")
+      Uri.parse(
+        "${scheme}://blocked?app=${Uri.encode(appName)}" +
+          "&package=${Uri.encode(blockedPackageName)}&reason=${reason.slug}"
+      )
     ).apply {
       addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-blocker",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "description": "Expo module for cross-platform app blocking. Android: UsageStatsManager + Overlay. iOS: Screen Time API (FamilyControls + ManagedSettings + DeviceActivity).",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -168,6 +168,13 @@ export function isAppBlocked(bundleIdentifier: string): boolean {
 // iOS-specific: Temporary unlock
 // ──────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Suppress blocking for `durationMinutes`, then auto-resume.
+ *
+ * iOS removes the Family Controls shields; Android pauses the foreground-service
+ * poll (the timer lives in the service, so it survives app backgrounding).
+ * Calling again replaces any active unlock. Android rounds to a whole minute (min 1).
+ */
 export async function temporaryUnlock(durationMinutes: number = 15): Promise<TemporaryUnlockResult> {
   if (Platform.OS === "android") {
     NativeModule.temporaryUnlockAndroid(Math.max(1, Math.round(durationMinutes)));
@@ -176,6 +183,7 @@ export async function temporaryUnlock(durationMinutes: number = 15): Promise<Tem
   return NativeModule.temporaryUnlock(durationMinutes);
 }
 
+/** iOS only — returns `false` on Android. On Android use `getRemainingUnlockTime() > 0`. */
 export function isTemporarilyUnlocked(): boolean {
   if (Platform.OS !== "ios") return false;
   return NativeModule.isTemporarilyUnlocked();
@@ -187,6 +195,12 @@ export function getRemainingUnlockTime(): number {
   return NativeModule.getRemainingUnlockTime();
 }
 
+/**
+ * End an active temporary unlock immediately and re-block.
+ *
+ * iOS restores the shields; Android cancels the unlock and re-blocks the
+ * foreground app on the next poll. Safe to call when nothing is unlocked.
+ */
 export async function relockApps(): Promise<RelockResult> {
   if (Platform.OS === "android") {
     NativeModule.relockAndroid();