expo-app-blocker 0.1.64 → 0.1.65

package/README.md

@@ -513,10 +513,10 @@ await relockApps();                        // drop the budget now, re-block imme
 
 | | Android | iOS |
 |---|---|---|
-| Mechanism | Foreground-service poll consumes the budget each tick spent inside a blocked app | DeviceActivity usage-threshold event re-applies the Family Controls shield after N minutes of measured usage |
-| `getRemainingUnlockTime()` | Live — ticks down while inside a blocked app, freezes otherwise | Returns the **granted** budget; iOS can't expose live usage, so it stays flat until the threshold fires (then `0`) |
+| Mechanism | Foreground-service poll consumes the budget each tick spent inside a blocked app | DeviceActivity usage-threshold events stepped ~every 30s of the budget; the monitor extension records consumed seconds and re-applies the shield on the final step |
+| `getRemainingUnlockTime()` | Live — ticks down by the second while inside a blocked app, freezes otherwise | **~30s-granular** — steps down as measured usage accrues (the monitor writes consumed seconds to the App Group), freezes when the apps aren't used |
 | `isTemporarilyUnlocked()` | Returns `false` (use `getRemainingUnlockTime() > 0`) | `true` while budget remains |
-| Caveats | — | Apple thresholds are unreliable below a few minutes; unspent budget is cleared at the daily schedule boundary (midnight) |
+| Caveats | — | Apple thresholds are coarse/unreliable below ~a minute, so the finest steps may fire late or be skipped (later steps + the final threshold still re-block, bounding overshoot to ~one step); large budgets auto-coarsen the step to stay under the event cap; unspent budget is cleared at the daily boundary (midnight) |
 
 > **Android only:** when the budget runs out while the user is still inside a
 > blocked app, the deep link fires with `reason=expired` (see

package/ios/ExpoAppBlockerModule.swift

@@ -18,9 +18,25 @@ public class ExpoAppBlockerModule: Module {
   // value > 0 means a temporary unlock is active. Enforcement is usage-based: the
   // shield is re-applied by the DeviceActivityMonitor once cumulative foreground
   // usage of the blocked apps reaches the threshold (see `startUsageBasedRelock`).
+  // Stores the granted budget in SECONDS (Int). Presence with value > 0 means a
+  // temporary unlock is active; the monitor reads it to know when to fully re-block.
   private let temporaryUnlockKey = "appBlocker.temporaryUnlock.v1"
   private let unlockActivityName = "appBlocker.temporaryUnlock"
-  private let usageEventName = "appBlocker.usageThreshold"
+  // Sub-minute usage steps. We register one DeviceActivityEvent per `usageStepSeconds`
+  // of the budget (threshold = k×step seconds of measured usage). Each step's
+  // eventDidReachThreshold lets the monitor extension write consumed SECONDS back to
+  // the App Group — readable by the host app (unlike DeviceActivityReport). The event
+  // name carries its threshold in seconds (`appBlocker.usageStep.<seconds>`).
+  private let usageStepEventPrefix = "appBlocker.usageStep."
+  // Consumed seconds of the active unlock, written by the monitor extension.
+  private let usageConsumedKey = "appBlocker.usageConsumedSeconds.v1"
+  // Target resolution. Apple's thresholds are coarse/unreliable below ~a minute, so
+  // 30s is a best-effort finer grain; the per-step events that don't fire are still
+  // backstopped by later (coarser-elapsed) ones and the final re-block threshold.
+  private let usageStepSeconds = 30
+  // Cap on registered step events. For large budgets the step auto-coarsens so the
+  // event count stays under this (Apple degrades with too many events).
+  private let maxUsageSteps = 60
   private let pendingUnlockKey = "appBlocker.pendingUnlock.v1"
   private let minimumTemporaryUnlockMinutes = 1
   private var didLoadPersistedConfig = false
@@ -170,7 +186,7 @@ public class ExpoAppBlockerModule: Module {
         self.currentBlockConfig = nil
         self.userDefaults.removeObject(forKey: self.blockConfigStorageKey)
         self.sharedDefaults?.removeObject(forKey: self.blockConfigStorageKey)
-        self.sharedDefaults?.removeObject(forKey: self.temporaryUnlockKey)
+        self.clearUnlockState()
       }
     }
 
@@ -206,6 +222,7 @@ public class ExpoAppBlockerModule: Module {
 
         let budgetSeconds = sanitizedDurationMinutes * 60
         self.sharedDefaults?.set(budgetSeconds, forKey: self.temporaryUnlockKey)
+        self.sharedDefaults?.set(0, forKey: self.usageConsumedKey)
 
         DispatchQueue.main.async {
           self.store.shield.applications = nil
@@ -216,7 +233,7 @@ public class ExpoAppBlockerModule: Module {
         // Re-block once cumulative *usage* of the blocked apps hits the budget.
         // iOS only counts foreground time, so the budget pauses/resumes for free.
         do {
-          try self.startUsageBasedRelock(minutes: sanitizedDurationMinutes)
+          try self.startUsageBasedRelock(budgetSeconds: budgetSeconds)
         } catch {
           // Monitoring failed to start (e.g. threshold below Apple's granularity).
           // The unlock still happens; the shield falls back to re-applying on the
@@ -237,15 +254,16 @@ public class ExpoAppBlockerModule: Module {
     }
 
     Function("isTemporarilyUnlocked") { () -> Bool in
-      return self.remainingUnlockBudgetSeconds() > 0
+      return self.remainingUnlockSeconds() > 0
     }
 
-    // NOTE: On iOS this returns the *granted* budget, not a live remaining count —
-    // Apple does not expose cumulative usage to the app, so the value does not tick
-    // down as the blocked apps are used. It drops to 0 once the usage threshold
-    // re-applies the shield (or on relock).
+    // Remaining = granted budget minus the consumed minutes the monitor extension
+    // has written to the App Group as usage accrued. Steps down by ~1 minute per
+    // minute of actual blocked-app usage and freezes while the apps aren't used.
+    // It's minute-granular (not smooth seconds) and may lag real usage slightly —
+    // Apple's thresholds are coarse. Drops to 0 once the budget is fully spent.
     Function("getRemainingUnlockTime") { () -> Int in
-      return self.remainingUnlockBudgetSeconds()
+      return self.remainingUnlockSeconds()
     }
 
     AsyncFunction("relockApps") { (promise: Promise) in
@@ -341,7 +359,7 @@ public class ExpoAppBlockerModule: Module {
 
     ensureLoadedPersistedConfig()
 
-    if remainingUnlockBudgetSeconds() > 0 {
+    if remainingUnlockSeconds() > 0 {
       // Unlock still active — keep the shield off. The usage-threshold monitor
       // started in `temporaryUnlock` persists across app launches and will
       // re-apply the shield once the usage budget is spent.
@@ -465,7 +483,7 @@ public class ExpoAppBlockerModule: Module {
   }
 
   private func relockApps() {
-    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
+    clearUnlockState()
     cancelRelockActivity()
     ensureLoadedPersistedConfig()
 
@@ -482,19 +500,26 @@ public class ExpoAppBlockerModule: Module {
   // MARK: - Activity Scheduling
 
   /// Start usage-based monitoring: re-apply the shield once cumulative foreground
-  /// usage of the blocked apps reaches `minutes`. iOS counts only active usage, so
-  /// the budget naturally pauses when the apps aren't in use and resumes on return.
+  /// usage of the blocked apps reaches `budgetSeconds`. iOS counts only active usage,
+  /// so the budget naturally pauses when the apps aren't in use and resumes on return.
+  ///
+  /// We register a series of threshold events stepping by `usageStepSeconds` (auto-
+  /// coarsened so the count stays under `maxUsageSteps`). The event name carries its
+  /// threshold in seconds (`usageStepEventPrefix + <seconds>`). Each step's
+  /// `eventDidReachThreshold` (in the DeviceActivityMonitor extension) writes the
+  /// consumed-second count to the App Group — giving the host app a sub-minute,
+  /// pause-when-away consumed counter (`getRemainingUnlockTime`). The final step
+  /// (== budget) is where the monitor re-applies the shield.
   ///
-  /// Uses an all-day repeating schedule purely as a container for the usage event;
-  /// the `eventDidReachThreshold` callback (in the DeviceActivityMonitor extension)
-  /// does the actual relock. `repeats: true` keeps the monitor alive across days so
-  /// apps are never left unlocked without enforcement; the tradeoff is that
-  /// `intervalDidEnd` clears any unspent budget at the day boundary (earned time
-  /// does not carry across midnight).
+  /// Uses an all-day repeating schedule purely as a container for the events.
+  /// `repeats: true` keeps the monitor alive across days so apps are never left
+  /// unlocked without enforcement; the tradeoff is that `intervalDidEnd` clears any
+  /// unspent budget at the day boundary (earned time does not carry across midnight).
   ///
-  /// Note: Apple's usage thresholds are unreliable below a few minutes — very small
-  /// budgets may relock late or only at the daily interval boundary.
-  private func startUsageBasedRelock(minutes: Int) throws {
+  /// Note: Apple's usage thresholds are coarse/unreliable below ~a minute, so the
+  /// finest steps may fire late or be skipped — later steps and the final threshold
+  /// still re-block, bounding overshoot to roughly one step.
+  private func startUsageBasedRelock(budgetSeconds: Int) throws {
     scheduleLock.lock()
     defer { scheduleLock.unlock() }
 
@@ -513,23 +538,46 @@ public class ExpoAppBlockerModule: Module {
       return
     }
 
-    let event = DeviceActivityEvent(
-      applications: appTokens,
-      categories: categoryTokens,
-      webDomains: webDomainTokens,
-      threshold: DateComponents(minute: max(1, minutes))
-    )
+    let budget = max(1, budgetSeconds)
+    // Step by usageStepSeconds, but coarsen so we never exceed maxUsageSteps events.
+    let step = max(usageStepSeconds, Int(ceil(Double(budget) / Double(maxUsageSteps))))
+    var thresholds: [Int] = []
+    var t = step
+    while t < budget {
+      thresholds.append(t)
+      t += step
+    }
+    thresholds.append(budget) // always include the exact budget as the final re-block
+
+    var events: [DeviceActivityEvent.Name: DeviceActivityEvent] = [:]
+    for seconds in thresholds {
+      events[DeviceActivityEvent.Name("\(usageStepEventPrefix)\(seconds)")] = DeviceActivityEvent(
+        applications: appTokens,
+        categories: categoryTokens,
+        webDomains: webDomainTokens,
+        threshold: dateComponents(fromSeconds: seconds)
+      )
+    }
 
+    // CRITICAL: the interval must start ~now, not at midnight. DeviceActivityEvent
+    // thresholds measure usage accumulated *within the interval, from its start*. An
+    // all-day [00:00, 23:59] interval would count usage since midnight — so any prior
+    // blocked-app use today would have already crossed the thresholds before monitoring
+    // began, and the system never fires a (new) crossing → the shield never re-applies.
+    // Starting the interval at the current time makes thresholds count from the unlock
+    // moment. repeats:false because we re-register on every unlock.
+    let now = Date()
+    let startComps = Calendar.current.dateComponents([.hour, .minute, .second], from: now)
     let schedule = DeviceActivitySchedule(
-      intervalStart: DateComponents(hour: 0, minute: 0, second: 0),
+      intervalStart: startComps,
       intervalEnd: DateComponents(hour: 23, minute: 59, second: 59),
-      repeats: true
+      repeats: false
     )
 
     try activityCenter.startMonitoring(
       DeviceActivityName(unlockActivityName),
       during: schedule,
-      events: [DeviceActivityEvent.Name(usageEventName): event]
+      events: events
     )
   }
 
@@ -545,12 +593,33 @@ public class ExpoAppBlockerModule: Module {
   }
 
   private func isTemporarilyUnlockedInternal() -> Bool {
-    return remainingUnlockBudgetSeconds() > 0
+    return remainingUnlockSeconds() > 0
   }
 
-  /// Granted earned-time budget in seconds (0 if no active unlock). See `temporaryUnlockKey`.
-  private func remainingUnlockBudgetSeconds() -> Int {
-    return (sharedDefaults?.object(forKey: temporaryUnlockKey) as? Int) ?? 0
+  /// Clear all persisted unlock state (budget + consumed counter).
+  private func clearUnlockState() {
+    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
+    sharedDefaults?.removeObject(forKey: usageConsumedKey)
+  }
+
+  /// Seconds of earned time still available: the granted budget minus the seconds
+  /// of blocked-app usage the monitor extension has recorded. 0 if no active unlock
+  /// or the budget is fully consumed. Clamped at 0.
+  private func remainingUnlockSeconds() -> Int {
+    let budgetSeconds = (sharedDefaults?.object(forKey: temporaryUnlockKey) as? Int) ?? 0
+    if budgetSeconds <= 0 { return 0 }
+    let consumedSeconds = (sharedDefaults?.object(forKey: usageConsumedKey) as? Int) ?? 0
+    return max(0, budgetSeconds - consumedSeconds)
+  }
+
+  /// Build a DateComponents threshold from a total number of seconds (normalized
+  /// into hour/minute/second so the system reads it cleanly).
+  private func dateComponents(fromSeconds total: Int) -> DateComponents {
+    return DateComponents(
+      hour: total / 3600,
+      minute: (total % 3600) / 60,
+      second: total % 60
+    )
   }
 
   // MARK: - Serialization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-blocker",
-  "version": "0.1.64",
+  "version": "0.1.65",
   "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/targets/DeviceActivityMonitor/DeviceActivityMonitor.swift

@@ -4,11 +4,19 @@ import FamilyControls
 import Foundation
 
 @available(iOS 15.0, *)
-class AppBlockerDeviceActivityMonitor: DeviceActivityMonitor {
+// NOTE: the class name MUST be `DeviceActivityMonitorExtension` — it has to match
+// the `NSExtensionPrincipalClass` (`$(PRODUCT_MODULE_NAME).DeviceActivityMonitorExtension`)
+// that @bacons/apple-targets writes into the extension's Info.plist. If it doesn't
+// match, iOS cannot instantiate the extension and NONE of the callbacks fire.
+class DeviceActivityMonitorExtension: DeviceActivityMonitor {
   // CONFIGURE: Replace with your App Group identifier
   private let appGroupIdentifier = "APP_GROUP_PLACEHOLDER"
   private let temporaryUnlockKey = "appBlocker.temporaryUnlock.v1"
   private let blockConfigStorageKey = "appBlocker.blockConfiguration.v1"
+  // Keep these in sync with ExpoAppBlockerModule.swift. temporaryUnlockKey holds the
+  // budget in seconds; usageConsumedKey accumulates consumed seconds.
+  private let usageStepEventPrefix = "appBlocker.usageStep."
+  private let usageConsumedKey = "appBlocker.usageConsumedSeconds.v1"
 
   private let store = ManagedSettingsStore()
   private var sharedDefaults: UserDefaults?
@@ -20,24 +28,61 @@ class AppBlockerDeviceActivityMonitor: DeviceActivityMonitor {
 
   override func intervalDidEnd(for activity: DeviceActivityName) {
     super.intervalDidEnd(for: activity)
-    // Daily safety net: clear any active unlock budget at the schedule boundary.
-    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
-    reapplyBlockConfiguration()
+    // Intentionally a no-op. Re-block is driven solely by eventDidReachThreshold
+    // (the usage budget). We must NOT clear unlock state or reapply the shield here:
+    // stopMonitoring() during a re-grant also fires intervalDidEnd, which would wipe
+    // the freshly-granted budget and re-shield the apps immediately after the user
+    // earned time. (Tradeoff: an unspent budget is not force-cleared at the daily
+    // schedule boundary — an acceptable edge case.)
   }
 
   override func intervalDidStart(for activity: DeviceActivityName) {
     super.intervalDidStart(for: activity)
   }
 
+  // Fires once per usage step (threshold = N seconds of measured blocked-app use).
+  // We write the consumed-second count back to the App Group so the host app can
+  // show a live, pause-when-away countdown; once consumed reaches the budget we
+  // clear the unlock and re-apply the shield.
   override func eventDidReachThreshold(
     _ event: DeviceActivityEvent.Name,
     activity: DeviceActivityName
   ) {
     super.eventDidReachThreshold(event, activity: activity)
-    // The user has spent their earned usage budget on the blocked apps —
-    // clear the unlock and re-apply the shield.
+
+    let stepSeconds = parseStepSeconds(from: event.rawValue)
+    guard stepSeconds > 0 else {
+      // Unknown event — treat as a full relock to stay safe.
+      clearUnlockState()
+      reapplyBlockConfiguration()
+      return
+    }
+
+    // Record consumed seconds monotonically (steps can arrive out of order).
+    let prev = sharedDefaults?.integer(forKey: usageConsumedKey) ?? 0
+    if stepSeconds > prev {
+      sharedDefaults?.set(stepSeconds, forKey: usageConsumedKey)
+    }
+
+    let budgetSeconds = sharedDefaults?.integer(forKey: temporaryUnlockKey) ?? 0
+    if budgetSeconds <= 0 || stepSeconds >= budgetSeconds {
+      // Budget fully spent — re-block.
+      clearUnlockState()
+      reapplyBlockConfiguration()
+    }
+  }
+
+  /// Extract the threshold seconds from an event name like `appBlocker.usageStep.90`;
+  /// 0 if not a usage step.
+  private func parseStepSeconds(from rawName: String) -> Int {
+    guard rawName.hasPrefix(usageStepEventPrefix) else { return 0 }
+    let suffix = rawName.dropFirst(usageStepEventPrefix.count)
+    return Int(suffix) ?? 0
+  }
+
+  private func clearUnlockState() {
     sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
-    reapplyBlockConfiguration()
+    sharedDefaults?.removeObject(forKey: usageConsumedKey)
   }
 
   private func reapplyBlockConfiguration() {