capacitor-mobilecron 0.1.0

package/README.md

@@ -0,0 +1,281 @@
+# capacitor-mobilecron
+
+> Lightweight Capacitor scheduling primitive — register jobs, get `jobDue` events when they fire, across web, Android, and iOS.
+
+[![npm version](https://img.shields.io/npm/v/capacitor-mobilecron)](https://www.npmjs.com/package/capacitor-mobilecron)
+[![CI](https://github.com/rogelioRuiz/capacitor-mobilecron/actions/workflows/ci.yml/badge.svg)](https://github.com/rogelioRuiz/capacitor-mobilecron/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Overview
+
+`capacitor-mobilecron` manages a set of named, persistent cron-like jobs and emits events when they are due. It handles:
+
+- **Repeating intervals** (`every: N ms`) with optional anchor alignment
+- **One-shot schedules** (`at: epoch ms`) that auto-disable after firing
+- **Active-hour windows** — restrict jobs to HH:MM–HH:MM ranges with timezone support
+- **Network / charging constraints** — skip a job when connectivity or power is absent
+- **Scheduling modes** — `eco` (60s watchdog), `balanced` (30s), `aggressive` (15s)
+- **App foreground wakeup** — immediately checks overdue jobs when the app comes to the foreground
+- **Persistent state** — job registry survives app restarts via `@capacitor/preferences` (falls back to `localStorage` on web)
+
+The web implementation is fully functional and self-contained. Android and iOS stubs satisfy the Capacitor plugin contract and can be extended with native WorkManager / BGTaskScheduler wakeups.
+
+## Installation
+
+```bash
+npm install capacitor-mobilecron
+npx cap sync
+```
+
+**Peer dependencies** you need in your Capacitor app:
+
+```bash
+npm install @capacitor/core @capacitor/preferences
+# @capacitor/app is optional — enables foreground-wakeup check
+npm install @capacitor/app
+```
+
+## Quick start
+
+```typescript
+import { MobileCron } from 'capacitor-mobilecron'
+
+// Listen for due events
+await MobileCron.addListener('jobDue', ({ id, name, firedAt, source, data }) => {
+  console.log(`Job "${name}" fired at ${new Date(firedAt).toISOString()} via ${source}`)
+})
+
+// Register a repeating job — every 5 minutes
+const { id } = await MobileCron.register({
+  name: 'sync-data',
+  schedule: { kind: 'every', everyMs: 5 * 60 * 1000 },
+})
+
+// Register a one-shot job — fires at a specific time
+await MobileCron.register({
+  name: 'daily-reminder',
+  schedule: { kind: 'at', atMs: Date.now() + 24 * 60 * 60 * 1000 },
+})
+```
+
+## API
+
+### `register(options)`
+
+Register a new job. Returns the job `id`.
+
+```typescript
+const { id } = await MobileCron.register({
+  name: 'my-job',
+  schedule: { kind: 'every', everyMs: 60_000 },       // every 60 s
+  activeHours: { start: '08:00', end: '22:00', tz: 'America/Chicago' },
+  requiresNetwork: true,
+  requiresCharging: false,
+  priority: 'normal',
+  data: { userId: '42' },                              // passed back in jobDue event
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | `string` | Human-readable label |
+| `schedule` | `CronSchedule` | When to fire (see below) |
+| `activeHours` | `ActiveHours?` | Restrict firing to a time window |
+| `requiresNetwork` | `boolean?` | Skip when offline |
+| `requiresCharging` | `boolean?` | Skip when not charging |
+| `priority` | `'low' \| 'normal' \| 'high'?` | Scheduling hint |
+| `data` | `Record<string, unknown>?` | Arbitrary payload returned in events |
+
+### Schedules
+
+```typescript
+// Repeat every N ms (minimum 60 000 ms on native)
+{ kind: 'every', everyMs: 300_000 }
+
+// Repeat every N ms, aligned to an anchor timestamp
+{ kind: 'every', everyMs: 3600_000, anchorMs: Date.now() }
+
+// Fire once at an absolute epoch timestamp
+{ kind: 'at', atMs: Date.parse('2025-01-01T09:00:00Z') }
+```
+
+### `unregister({ id })`
+
+Remove a job and stop it from firing.
+
+```typescript
+await MobileCron.unregister({ id })
+```
+
+### `update({ id, ...partial })`
+
+Patch an existing job without losing its state.
+
+```typescript
+await MobileCron.update({
+  id,
+  schedule: { kind: 'every', everyMs: 10 * 60 * 1000 },
+  activeHours: { start: '09:00', end: '17:00' },
+})
+```
+
+### `list()`
+
+Returns all registered jobs sorted by next due time.
+
+```typescript
+const { jobs } = await MobileCron.list()
+for (const job of jobs) {
+  console.log(job.name, 'next due at', new Date(job.nextDueAt ?? 0).toISOString())
+}
+```
+
+### `triggerNow({ id })`
+
+Force a job to fire immediately (source = `'manual'`).
+
+```typescript
+await MobileCron.triggerNow({ id })
+```
+
+### `pauseAll()` / `resumeAll()`
+
+Suspend / resume all job checks globally.
+
+```typescript
+await MobileCron.pauseAll()
+await MobileCron.resumeAll()
+```
+
+### `setMode({ mode })`
+
+Control how frequently the watchdog timer checks for due jobs.
+
+| Mode | Interval | Use case |
+|------|----------|---------|
+| `'eco'` | 60 s | Battery-sensitive background |
+| `'balanced'` | 30 s | Default |
+| `'aggressive'` | 15 s | Real-time UX needs |
+
+```typescript
+await MobileCron.setMode({ mode: 'aggressive' })
+```
+
+### `getStatus()`
+
+Returns scheduler diagnostics.
+
+```typescript
+const status = await MobileCron.getStatus()
+// {
+//   paused: false,
+//   mode: 'balanced',
+//   platform: 'android',
+//   activeJobCount: 3,
+//   nextDueAt: 1719000000000,
+//   android: { workManagerActive: true, chargingReceiverActive: false }
+// }
+```
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `jobDue` | `JobDueEvent` | A job fired |
+| `jobSkipped` | `JobSkippedEvent` | A due job was skipped (constraint not met) |
+| `overdueJobs` | `OverdueEvent` | Emitted on foreground resume if jobs are overdue |
+| `statusChanged` | `CronStatus` | Scheduler state changed |
+
+```typescript
+MobileCron.addListener('jobSkipped', ({ id, name, reason }) => {
+  // reason: 'outside_active_hours' | 'paused' | 'requires_network' | 'requires_charging'
+  console.warn(`Job ${name} skipped: ${reason}`)
+})
+
+MobileCron.addListener('overdueJobs', ({ count, jobs }) => {
+  console.warn(`${count} jobs were overdue on resume`)
+})
+```
+
+## Advanced: `MobileCronScheduler`
+
+The package also exports the plain TypeScript scheduler class that powers the web plugin. Use it directly in Node.js, React Native, or any non-Capacitor environment:
+
+```typescript
+import { MobileCronScheduler } from 'capacitor-mobilecron'
+
+const scheduler = new MobileCronScheduler({
+  platform: 'web',
+  onJobDue: (event) => handleJobDue(event),
+  onJobSkipped: (event) => console.warn('skipped', event),
+})
+
+await scheduler.init()
+
+const { id } = await scheduler.register({
+  name: 'heartbeat',
+  schedule: { kind: 'every', everyMs: 30_000 },
+})
+
+// Later — check due jobs from a native wakeup callback
+scheduler.checkDueJobs('workmanager')
+
+// Teardown
+await scheduler.destroy()
+```
+
+## iOS / Android native wakeups
+
+The web/JS watchdog is the primary scheduling mechanism. For true background execution extend the native stubs:
+
+### Android
+
+Wire `CronWorker` into `WorkManager` periodic tasks and call `bridge.checkDueJobs("workmanager")`. Register `ChargingReceiver` in the manifest for charging wakeups.
+
+### iOS
+
+Register a `BGAppRefreshTask` / `BGProcessingTask` in your `AppDelegate` and call the plugin method to check due jobs from there.
+
+## Testing
+
+### Unit tests — no device needed
+
+The scheduler core is pure TypeScript and fully testable without a phone:
+
+```bash
+npm test              # run 52 unit tests (instant)
+npm run test:watch    # TDD watch mode
+npm run test:coverage # coverage report
+```
+
+Tests cover schedule computation, active-hour windows, persistence, pause/resume, skip logic, and more.
+
+### Device E2E tests (Android, via CDP)
+
+Full integration suite against a running Android app — 7 sections, 40+ tests:
+
+```bash
+# 1. Forward CDP port from device
+adb forward tcp:9222 localabstract:webview_devtools_remote_$(adb shell pidof io.mobileclaw.reference)
+
+# 2. Run
+npm run test:e2e
+```
+
+See [`tests/e2e/test-e2e.mjs`](tests/e2e/test-e2e.mjs) for coverage details.
+
+## Contributing
+
+```bash
+git clone https://github.com/rogelioRuiz/capacitor-mobilecron.git
+cd capacitor-mobilecron
+npm install
+npm test              # unit tests — runs in seconds, no device
+npm run build         # compile TypeScript
+npm run lint          # Biome linter
+npm run typecheck     # TypeScript strict mode
+```
+
+## License
+
+MIT © Rogelio Ruiz

package/android/build.gradle

@@ -0,0 +1,45 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.1.5'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.5.1'
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace "io.mobilecron"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+        versionCode 1
+        versionName "0.1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        consumerProguardFiles 'proguard-rules.pro'
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation "org.jetbrains.kotlin:kotlin-stdlib"
+    implementation "androidx.work:work-runtime-ktx:2.9.0"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/proguard-rules.pro

@@ -0,0 +1,2 @@
+# capacitor-mobilecron ProGuard rules
+-keep class io.mobilecron.** { *; }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,5 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="io.mobilecron">
+    <application>
+        <!-- Receiver is dynamically registered in phase 1; manifest entry not required. -->
+    </application>
+</manifest>

package/android/src/main/java/io/mobilecron/ChargingReceiver.kt

@@ -0,0 +1,13 @@
+package io.mobilecron
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+
+class ChargingReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context?, intent: Intent?) {
+        if (intent?.action == Intent.ACTION_POWER_CONNECTED) {
+            CronBridge.wake("charging")
+        }
+    }
+}

package/android/src/main/java/io/mobilecron/CronBridge.kt

@@ -0,0 +1,20 @@
+package io.mobilecron
+
+import android.os.Handler
+import android.os.Looper
+
+object CronBridge {
+    @Volatile
+    var plugin: MobileCronPlugin? = null
+
+    fun wake(source: String) {
+        val current = plugin ?: return
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            current.notifyFromBackground(source)
+        } else {
+            Handler(Looper.getMainLooper()).post {
+                plugin?.notifyFromBackground(source)
+            }
+        }
+    }
+}

package/android/src/main/java/io/mobilecron/CronChainWorker.kt

@@ -0,0 +1,36 @@
+package io.mobilecron
+
+import android.content.Context
+import androidx.work.CoroutineWorker
+import androidx.work.ExistingWorkPolicy
+import androidx.work.OneTimeWorkRequestBuilder
+import androidx.work.WorkManager
+import androidx.work.WorkerParameters
+import java.util.concurrent.TimeUnit
+
+class CronChainWorker(
+    appContext: Context,
+    params: WorkerParameters
+) : CoroutineWorker(appContext, params) {
+    override suspend fun doWork(): Result {
+        CronBridge.wake("workmanager_chain")
+        enqueueNext(applicationContext, 5)
+        return Result.success()
+    }
+
+    companion object {
+        private const val UNIQUE_NAME = "mobilecron_chain"
+
+        fun enqueueNext(context: Context, delayMinutes: Long) {
+            val request = OneTimeWorkRequestBuilder<CronChainWorker>()
+                .setInitialDelay(delayMinutes, TimeUnit.MINUTES)
+                .build()
+
+            WorkManager.getInstance(context).enqueueUniqueWork(
+                UNIQUE_NAME,
+                ExistingWorkPolicy.REPLACE,
+                request
+            )
+        }
+    }
+}

package/android/src/main/java/io/mobilecron/CronWorker.kt

@@ -0,0 +1,15 @@
+package io.mobilecron
+
+import android.content.Context
+import androidx.work.CoroutineWorker
+import androidx.work.WorkerParameters
+
+class CronWorker(
+    appContext: Context,
+    params: WorkerParameters
+) : CoroutineWorker(appContext, params) {
+    override suspend fun doWork(): Result {
+        CronBridge.wake("workmanager")
+        return Result.success()
+    }
+}

package/android/src/main/java/io/mobilecron/MobileCronPlugin.kt

@@ -0,0 +1,234 @@
+package io.mobilecron
+
+import android.content.Intent
+import android.content.IntentFilter
+import androidx.work.Constraints
+import androidx.work.ExistingPeriodicWorkPolicy
+import androidx.work.ExistingWorkPolicy
+import androidx.work.NetworkType
+import androidx.work.OneTimeWorkRequestBuilder
+import androidx.work.PeriodicWorkRequestBuilder
+import androidx.work.WorkManager
+import com.getcapacitor.JSArray
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.TimeUnit
+
+@CapacitorPlugin(name = "MobileCron")
+class MobileCronPlugin : Plugin() {
+    private val jobs = ConcurrentHashMap<String, JSObject>()
+    private var paused = false
+    private var mode = "balanced"
+    private var chargingReceiver: ChargingReceiver? = null
+
+    override fun load() {
+        super.load()
+        CronBridge.plugin = this
+        registerChargingReceiver()
+        scheduleWorkManager()
+    }
+
+    override fun handleOnDestroy() {
+        super.handleOnDestroy()
+        if (CronBridge.plugin === this) {
+            CronBridge.plugin = null
+        }
+        chargingReceiver?.let {
+            runCatching { context.unregisterReceiver(it) }
+        }
+        chargingReceiver = null
+    }
+
+    internal fun notifyFromBackground(source: String) {
+        // Native phase-1 skeleton: background wakes are surfaced, but due-job evaluation is implemented in TS web layer.
+        val payload = JSObject()
+        payload.put("source", source)
+        payload.put("paused", paused)
+        notifyListeners("statusChanged", buildStatus())
+        notifyListeners("nativeWake", payload)
+    }
+
+    private fun scheduleWorkManager() {
+        val wm = WorkManager.getInstance(context)
+        if (mode == "aggressive") {
+            val request = OneTimeWorkRequestBuilder<CronChainWorker>()
+                .setInitialDelay(5, TimeUnit.MINUTES)
+                .build()
+            wm.enqueueUniqueWork("mobilecron_chain", ExistingWorkPolicy.REPLACE, request)
+            return
+        }
+
+        val constraintsBuilder = Constraints.Builder()
+        if (mode == "eco") {
+            constraintsBuilder.setRequiredNetworkType(NetworkType.UNMETERED)
+            constraintsBuilder.setRequiresBatteryNotLow(true)
+        } else {
+            constraintsBuilder.setRequiredNetworkType(NetworkType.CONNECTED)
+        }
+
+        val request = PeriodicWorkRequestBuilder<CronWorker>(15, TimeUnit.MINUTES)
+            .setConstraints(constraintsBuilder.build())
+            .build()
+
+        wm.enqueueUniquePeriodicWork(
+            "mobilecron_periodic",
+            ExistingPeriodicWorkPolicy.UPDATE,
+            request
+        )
+    }
+
+    private fun registerChargingReceiver() {
+        if (chargingReceiver != null) return
+        val receiver = ChargingReceiver()
+        context.registerReceiver(receiver, IntentFilter(Intent.ACTION_POWER_CONNECTED))
+        chargingReceiver = receiver
+    }
+
+    @PluginMethod
+    fun register(call: PluginCall) {
+        val name = call.getString("name")?.trim()
+        if (name.isNullOrEmpty()) {
+            call.reject("Job name is required")
+            return
+        }
+
+        val id = UUID.randomUUID().toString()
+        val record = JSObject()
+        record.put("id", id)
+        record.put("name", name)
+        record.put("enabled", true)
+        record.put("schedule", call.getObject("schedule") ?: JSObject())
+        record.put("activeHours", call.getObject("activeHours"))
+        record.put("requiresNetwork", call.getBoolean("requiresNetwork", false))
+        record.put("requiresCharging", call.getBoolean("requiresCharging", false))
+        record.put("priority", call.getString("priority", "normal"))
+        call.getObject("data")?.let { record.put("data", it) }
+        record.put("consecutiveSkips", 0)
+        jobs[id] = record
+
+        val result = JSObject()
+        result.put("id", id)
+        call.resolve(result)
+        notifyListeners("statusChanged", buildStatus())
+    }
+
+    @PluginMethod
+    fun unregister(call: PluginCall) {
+        val id = call.getString("id")
+        if (id == null) {
+            call.reject("id is required")
+            return
+        }
+        jobs.remove(id)
+        call.resolve()
+        notifyListeners("statusChanged", buildStatus())
+    }
+
+    @PluginMethod
+    fun update(call: PluginCall) {
+        val id = call.getString("id")
+        if (id == null) {
+            call.reject("id is required")
+            return
+        }
+        val existing = jobs[id]
+        if (existing == null) {
+            call.reject("Job not found")
+            return
+        }
+
+        call.getString("name")?.let { existing.put("name", it) }
+        call.getObject("schedule")?.let { existing.put("schedule", it) }
+        if (call.data.has("activeHours")) existing.put("activeHours", call.getObject("activeHours"))
+        if (call.data.has("requiresNetwork")) existing.put("requiresNetwork", call.getBoolean("requiresNetwork", false))
+        if (call.data.has("requiresCharging")) existing.put("requiresCharging", call.getBoolean("requiresCharging", false))
+        call.getString("priority")?.let { existing.put("priority", it) }
+        if (call.data.has("data")) existing.put("data", call.getObject("data"))
+
+        jobs[id] = existing
+        call.resolve()
+        notifyListeners("statusChanged", buildStatus())
+    }
+
+    @PluginMethod
+    fun list(call: PluginCall) {
+        val arr = JSArray()
+        jobs.values.forEach { arr.put(it) }
+        val result = JSObject()
+        result.put("jobs", arr)
+        call.resolve(result)
+    }
+
+    @PluginMethod
+    fun triggerNow(call: PluginCall) {
+        val id = call.getString("id")
+        if (id == null) {
+            call.reject("id is required")
+            return
+        }
+        val job = jobs[id]
+        if (job == null) {
+            call.reject("Job not found")
+            return
+        }
+
+        val payload = JSObject()
+        payload.put("id", id)
+        payload.put("name", job.getString("name"))
+        payload.put("firedAt", System.currentTimeMillis())
+        payload.put("source", "manual")
+        if (job.has("data")) payload.put("data", job.getJSONObject("data"))
+        notifyListeners("jobDue", payload)
+        call.resolve()
+    }
+
+    @PluginMethod
+    fun pauseAll(call: PluginCall) {
+        paused = true
+        call.resolve()
+        notifyListeners("statusChanged", buildStatus())
+    }
+
+    @PluginMethod
+    fun resumeAll(call: PluginCall) {
+        paused = false
+        call.resolve()
+        notifyListeners("statusChanged", buildStatus())
+    }
+
+    @PluginMethod
+    fun setMode(call: PluginCall) {
+        val next = call.getString("mode")
+        if (next !in listOf("eco", "balanced", "aggressive")) {
+            call.reject("mode must be eco|balanced|aggressive")
+            return
+        }
+        mode = next!!
+        scheduleWorkManager()
+        call.resolve()
+        notifyListeners("statusChanged", buildStatus())
+    }
+
+    @PluginMethod
+    fun getStatus(call: PluginCall) {
+        call.resolve(buildStatus())
+    }
+
+    private fun buildStatus(): JSObject {
+        val status = JSObject()
+        status.put("paused", paused)
+        status.put("mode", mode)
+        status.put("platform", "android")
+        status.put("activeJobCount", jobs.size)
+        status.put("android", JSObject().apply {
+            put("workManagerActive", true)
+            put("chargingReceiverActive", chargingReceiver != null)
+        })
+        return status
+    }
+}