capacitor-mobilecron 0.1.0

package/dist/esm/web.d.ts

@@ -0,0 +1,32 @@
+import { type PluginListenerHandle, WebPlugin } from '@capacitor/core';
+import type { CronJobOptions, CronStatus, JobDueEvent, JobSkippedEvent, MobileCronPlugin, OverdueEvent, SchedulingMode } from './definitions';
+export declare class MobileCronWeb extends WebPlugin implements MobileCronPlugin {
+    private readonly scheduler;
+    private readonly ready;
+    constructor();
+    register(options: CronJobOptions): Promise<{
+        id: string;
+    }>;
+    unregister(options: {
+        id: string;
+    }): Promise<void>;
+    update(options: {
+        id: string;
+    } & Partial<CronJobOptions>): Promise<void>;
+    list(): Promise<{
+        jobs: import('./definitions').CronJobStatus[];
+    }>;
+    triggerNow(options: {
+        id: string;
+    }): Promise<void>;
+    pauseAll(): Promise<void>;
+    resumeAll(): Promise<void>;
+    setMode(options: {
+        mode: SchedulingMode;
+    }): Promise<void>;
+    getStatus(): Promise<CronStatus>;
+    addListener(event: 'jobDue', handler: (data: JobDueEvent) => void): Promise<PluginListenerHandle>;
+    addListener(event: 'jobSkipped', handler: (data: JobSkippedEvent) => void): Promise<PluginListenerHandle>;
+    addListener(event: 'overdueJobs', handler: (data: OverdueEvent) => void): Promise<PluginListenerHandle>;
+    addListener(event: 'statusChanged', handler: (data: CronStatus) => void): Promise<PluginListenerHandle>;
+}

package/dist/esm/web.js

@@ -0,0 +1,54 @@
+import { WebPlugin } from '@capacitor/core';
+import { MobileCronScheduler } from './mobilecron';
+export class MobileCronWeb extends WebPlugin {
+    constructor() {
+        super();
+        this.scheduler = new MobileCronScheduler({
+            platform: 'web',
+            onJobDue: (event) => this.notifyListeners('jobDue', event),
+            onJobSkipped: (event) => this.notifyListeners('jobSkipped', event),
+            onOverdue: (event) => this.notifyListeners('overdueJobs', event),
+            onStatusChanged: (status) => this.notifyListeners('statusChanged', status),
+        });
+        this.ready = this.scheduler.init();
+    }
+    async register(options) {
+        await this.ready;
+        return this.scheduler.register(options);
+    }
+    async unregister(options) {
+        await this.ready;
+        return this.scheduler.unregister(options);
+    }
+    async update(options) {
+        await this.ready;
+        return this.scheduler.update(options);
+    }
+    async list() {
+        await this.ready;
+        return this.scheduler.list();
+    }
+    async triggerNow(options) {
+        await this.ready;
+        return this.scheduler.triggerNow(options);
+    }
+    async pauseAll() {
+        await this.ready;
+        return this.scheduler.pauseAll();
+    }
+    async resumeAll() {
+        await this.ready;
+        return this.scheduler.resumeAll();
+    }
+    async setMode(options) {
+        await this.ready;
+        return this.scheduler.setMode(options.mode);
+    }
+    async getStatus() {
+        await this.ready;
+        return this.scheduler.getStatus();
+    }
+    async addListener(eventName, listenerFunc) {
+        return super.addListener(eventName, listenerFunc);
+    }
+}

package/ios/Plugin/BGTaskManager.swift

@@ -0,0 +1,78 @@
+import Foundation
+import BackgroundTasks
+
+final class BGTaskManager {
+    struct Status {
+        var bgRefreshRegistered: Bool = false
+        var bgProcessingRegistered: Bool = false
+        var bgContinuedAvailable: Bool = false
+    }
+
+    private weak var plugin: MobileCronPlugin?
+    private(set) var status = Status()
+
+    init(plugin: MobileCronPlugin) {
+        self.plugin = plugin
+        self.status.bgContinuedAvailable = false
+    }
+
+    func registerBGTasks() {
+        status.bgRefreshRegistered = BGTaskScheduler.shared.register(
+            forTaskWithIdentifier: "io.mobilecron.refresh",
+            using: nil
+        ) { [weak self] task in
+            guard let refreshTask = task as? BGAppRefreshTask else {
+                task.setTaskCompleted(success: false)
+                return
+            }
+            self?.handleRefresh(refreshTask)
+        }
+
+        status.bgProcessingRegistered = BGTaskScheduler.shared.register(
+            forTaskWithIdentifier: "io.mobilecron.processing",
+            using: nil
+        ) { [weak self] task in
+            guard let processingTask = task as? BGProcessingTask else {
+                task.setTaskCompleted(success: false)
+                return
+            }
+            self?.handleProcessing(processingTask)
+        }
+
+        // iOS 26+ BGContinuedProcessingTask placeholder: keep runtime feature flag separate from compile-time SDK use.
+        status.bgContinuedAvailable = false
+    }
+
+    func scheduleRefresh() {
+        let request = BGAppRefreshTaskRequest(identifier: "io.mobilecron.refresh")
+        request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
+        try? BGTaskScheduler.shared.submit(request)
+    }
+
+    func scheduleProcessing(requiresExternalPower: Bool) {
+        let request = BGProcessingTaskRequest(identifier: "io.mobilecron.processing")
+        request.requiresExternalPower = requiresExternalPower
+        request.requiresNetworkConnectivity = false
+        request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
+        try? BGTaskScheduler.shared.submit(request)
+    }
+
+    private func handleRefresh(_ task: BGAppRefreshTask) {
+        scheduleRefresh()
+        task.expirationHandler = {
+            task.setTaskCompleted(success: false)
+        }
+        plugin?.handleBackgroundWake(source: "bgtask_refresh")
+        task.setTaskCompleted(success: true)
+    }
+
+    private func handleProcessing(_ task: BGProcessingTask) {
+        let mode = plugin?.currentMode ?? "balanced"
+        scheduleProcessing(requiresExternalPower: mode != "aggressive")
+        task.expirationHandler = {
+            task.setTaskCompleted(success: false)
+        }
+        plugin?.handleBackgroundWake(source: "bgtask_processing")
+        task.setTaskCompleted(success: true)
+    }
+}

package/ios/Plugin/MobileCronPlugin.m

@@ -0,0 +1,13 @@
+#import <Capacitor/Capacitor.h>
+
+CAP_PLUGIN(MobileCronPlugin, "MobileCron",
+           CAP_PLUGIN_METHOD(register, CAPPluginReturnPromise);
+           CAP_PLUGIN_METHOD(unregister, CAPPluginReturnPromise);
+           CAP_PLUGIN_METHOD(update, CAPPluginReturnPromise);
+           CAP_PLUGIN_METHOD(list, CAPPluginReturnPromise);
+           CAP_PLUGIN_METHOD(triggerNow, CAPPluginReturnPromise);
+           CAP_PLUGIN_METHOD(pauseAll, CAPPluginReturnPromise);
+           CAP_PLUGIN_METHOD(resumeAll, CAPPluginReturnPromise);
+           CAP_PLUGIN_METHOD(setMode, CAPPluginReturnPromise);
+           CAP_PLUGIN_METHOD(getStatus, CAPPluginReturnPromise);
+)

package/ios/Plugin/MobileCronPlugin.swift

@@ -0,0 +1,169 @@
+import Foundation
+import Capacitor
+
+@objc(MobileCronPlugin)
+public class MobileCronPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "MobileCronPlugin"
+    public let jsName = "MobileCron"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "register", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "unregister", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "update", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "list", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "triggerNow", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "pauseAll", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "resumeAll", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setMode", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getStatus", returnType: CAPPluginReturnPromise)
+    ]
+
+    private var jobs: [String: [String: Any]] = [:]
+    private var paused = false
+    private(set) var mode = "balanced"
+    var currentMode: String { mode }
+    private var bgManager: BGTaskManager?
+
+    public override func load() {
+        super.load()
+        let manager = BGTaskManager(plugin: self)
+        manager.registerBGTasks()
+        manager.scheduleRefresh()
+        manager.scheduleProcessing(requiresExternalPower: true)
+        self.bgManager = manager
+    }
+
+    func handleBackgroundWake(source: String) {
+        notifyListeners("statusChanged", data: buildStatus())
+        notifyListeners("nativeWake", data: ["source": source, "paused": paused])
+    }
+
+    @objc func register(_ call: CAPPluginCall) {
+        guard let name = call.getString("name")?.trimmingCharacters(in: .whitespacesAndNewlines), !name.isEmpty else {
+            call.reject("Job name is required")
+            return
+        }
+
+        let id = UUID().uuidString
+        var record: [String: Any] = [
+            "id": id,
+            "name": name,
+            "enabled": true,
+            "consecutiveSkips": 0
+        ]
+        if let schedule = call.getObject("schedule") { record["schedule"] = schedule }
+        if let activeHours = call.getObject("activeHours") { record["activeHours"] = activeHours }
+        if call.options.keys.contains("requiresNetwork") { record["requiresNetwork"] = call.getBool("requiresNetwork") ?? false }
+        if call.options.keys.contains("requiresCharging") { record["requiresCharging"] = call.getBool("requiresCharging") ?? false }
+        if let priority = call.getString("priority") { record["priority"] = priority }
+        if let data = call.getObject("data") { record["data"] = data }
+
+        jobs[id] = record
+        notifyListeners("statusChanged", data: buildStatus())
+        call.resolve(["id": id])
+    }
+
+    @objc func unregister(_ call: CAPPluginCall) {
+        guard let id = call.getString("id") else {
+            call.reject("id is required")
+            return
+        }
+        jobs.removeValue(forKey: id)
+        notifyListeners("statusChanged", data: buildStatus())
+        call.resolve()
+    }
+
+    @objc func update(_ call: CAPPluginCall) {
+        guard let id = call.getString("id") else {
+            call.reject("id is required")
+            return
+        }
+        guard var existing = jobs[id] else {
+            call.reject("Job not found")
+            return
+        }
+
+        if let name = call.getString("name") { existing["name"] = name }
+        if let schedule = call.getObject("schedule") { existing["schedule"] = schedule }
+        if call.options.keys.contains("activeHours") { existing["activeHours"] = call.getObject("activeHours") }
+        if call.options.keys.contains("requiresNetwork") { existing["requiresNetwork"] = call.getBool("requiresNetwork") ?? false }
+        if call.options.keys.contains("requiresCharging") { existing["requiresCharging"] = call.getBool("requiresCharging") ?? false }
+        if let priority = call.getString("priority") { existing["priority"] = priority }
+        if call.options.keys.contains("data") { existing["data"] = call.getObject("data") }
+
+        jobs[id] = existing
+        notifyListeners("statusChanged", data: buildStatus())
+        call.resolve()
+    }
+
+    @objc func list(_ call: CAPPluginCall) {
+        call.resolve(["jobs": Array(jobs.values)])
+    }
+
+    @objc func triggerNow(_ call: CAPPluginCall) {
+        guard let id = call.getString("id") else {
+            call.reject("id is required")
+            return
+        }
+        guard let job = jobs[id] else {
+            call.reject("Job not found")
+            return
+        }
+
+        var payload: [String: Any] = [
+            "id": id,
+            "name": (job["name"] as? String) ?? "",
+            "firedAt": Int(Date().timeIntervalSince1970 * 1000),
+            "source": "manual"
+        ]
+        if let data = job["data"] {
+            payload["data"] = data
+        }
+        notifyListeners("jobDue", data: payload)
+        call.resolve()
+    }
+
+    @objc func pauseAll(_ call: CAPPluginCall) {
+        paused = true
+        notifyListeners("statusChanged", data: buildStatus())
+        call.resolve()
+    }
+
+    @objc func resumeAll(_ call: CAPPluginCall) {
+        paused = false
+        notifyListeners("statusChanged", data: buildStatus())
+        call.resolve()
+    }
+
+    @objc func setMode(_ call: CAPPluginCall) {
+        guard let mode = call.getString("mode"), ["eco", "balanced", "aggressive"].contains(mode) else {
+            call.reject("mode must be eco|balanced|aggressive")
+            return
+        }
+        self.mode = mode
+        if let bgManager {
+            bgManager.scheduleRefresh()
+            bgManager.scheduleProcessing(requiresExternalPower: mode != "aggressive")
+        }
+        notifyListeners("statusChanged", data: buildStatus())
+        call.resolve()
+    }
+
+    @objc func getStatus(_ call: CAPPluginCall) {
+        call.resolve(buildStatus())
+    }
+
+    private func buildStatus() -> [String: Any] {
+        let diagnostics = bgManager?.status ?? .init()
+        return [
+            "paused": paused,
+            "mode": mode,
+            "platform": "ios",
+            "activeJobCount": jobs.count,
+            "ios": [
+                "bgRefreshRegistered": diagnostics.bgRefreshRegistered,
+                "bgProcessingRegistered": diagnostics.bgProcessingRegistered,
+                "bgContinuedAvailable": diagnostics.bgContinuedAvailable
+            ]
+        ]
+    }
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "capacitor-mobilecron",
+  "version": "0.1.0",
+  "description": "Capacitor scheduling primitive that emits job due events across web, Android, and iOS",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "capacitor": {
+    "android": {
+      "src": "android"
+    },
+    "ios": {
+      "src": "ios"
+    }
+  },
+  "files": [
+    "android/src",
+    "android/build.gradle",
+    "android/proguard-rules.pro",
+    "ios",
+    "dist",
+    "src",
+    "package.json",
+    "README.md"
+  ],
+  "author": "Rogelio Ruiz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rogelioRuiz/capacitor-mobilecron.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rogelioRuiz/capacitor-mobilecron/issues"
+  },
+  "homepage": "https://github.com/rogelioRuiz/capacitor-mobilecron#readme",
+  "keywords": [
+    "capacitor",
+    "plugin",
+    "scheduler",
+    "cron",
+    "mobile",
+    "background",
+    "jobs",
+    "android",
+    "ios"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "npx biome check .",
+    "lint:fix": "npx biome check --write .",
+    "format": "npx biome format --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "node tests/e2e/test-e2e.mjs",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@capacitor/core": ">=6.0.0",
+    "@capacitor/preferences": ">=6.0.0",
+    "@capacitor/app": ">=6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@capacitor/app": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@capacitor/app": "^6.0.0",
+    "@capacitor/core": "^6.0.0",
+    "@capacitor/preferences": "^6.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "happy-dom": "^17.5.5",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  }
+}

package/src/definitions.ts

@@ -0,0 +1,99 @@
+import type { PluginListenerHandle } from '@capacitor/core'
+
+export interface MobileCronPlugin {
+  register(options: CronJobOptions): Promise<{ id: string }>
+  unregister(options: { id: string }): Promise<void>
+  update(options: { id: string } & Partial<CronJobOptions>): Promise<void>
+  list(): Promise<{ jobs: CronJobStatus[] }>
+  triggerNow(options: { id: string }): Promise<void>
+
+  pauseAll(): Promise<void>
+  resumeAll(): Promise<void>
+  setMode(options: { mode: SchedulingMode }): Promise<void>
+  getStatus(): Promise<CronStatus>
+
+  addListener(event: 'jobDue', handler: (data: JobDueEvent) => void): Promise<PluginListenerHandle>
+  addListener(event: 'jobSkipped', handler: (data: JobSkippedEvent) => void): Promise<PluginListenerHandle>
+  addListener(event: 'overdueJobs', handler: (data: OverdueEvent) => void): Promise<PluginListenerHandle>
+  addListener(event: 'statusChanged', handler: (data: CronStatus) => void): Promise<PluginListenerHandle>
+}
+
+export interface CronJobOptions {
+  name: string
+  schedule: CronSchedule
+  activeHours?: ActiveHours
+  requiresNetwork?: boolean
+  requiresCharging?: boolean
+  priority?: 'low' | 'normal' | 'high'
+  data?: Record<string, unknown>
+}
+
+export interface CronSchedule {
+  kind: 'every' | 'at'
+  everyMs?: number
+  anchorMs?: number
+  atMs?: number
+}
+
+export interface ActiveHours {
+  start: string
+  end: string
+  tz?: string
+}
+
+export type SchedulingMode = 'eco' | 'balanced' | 'aggressive'
+
+export interface CronJobStatus {
+  id: string
+  name: string
+  enabled: boolean
+  schedule: CronSchedule
+  lastFiredAt?: number
+  nextDueAt?: number
+  consecutiveSkips: number
+  data?: Record<string, unknown>
+}
+
+export interface CronStatus {
+  paused: boolean
+  mode: SchedulingMode
+  platform: 'android' | 'ios' | 'web'
+  activeJobCount: number
+  nextDueAt?: number
+  android?: { workManagerActive: boolean; chargingReceiverActive: boolean }
+  ios?: {
+    bgRefreshRegistered: boolean
+    bgProcessingRegistered: boolean
+    bgContinuedAvailable: boolean
+  }
+}
+
+export interface JobDueEvent {
+  id: string
+  name: string
+  firedAt: number
+  source: WakeSource
+  data?: Record<string, unknown>
+}
+
+export type WakeSource =
+  | 'watchdog'
+  | 'workmanager'
+  | 'workmanager_chain'
+  | 'charging'
+  | 'foreground'
+  | 'bgtask_refresh'
+  | 'bgtask_processing'
+  | 'bgtask_continued'
+  | 'manual'
+
+export interface JobSkippedEvent {
+  id: string
+  name: string
+  reason: 'outside_active_hours' | 'paused' | 'requires_network' | 'requires_charging'
+}
+
+export interface OverdueEvent {
+  count: number
+  jobs: Array<{ id: string; name: string; overdueMs: number }>
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './definitions'
+export * from './mobilecron'
+export { MobileCron } from './plugin'