expo-app-blocker 0.1.62 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-blocker",
-  "version": "0.1.62",
+  "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();