app.power - Power & Battery API

Battery status, power information, and system uptime.

Methods

app.power.battery()

Get battery information.

Returns: table|nil - returns nil on desktop Macs

Return fields:

• level (number) - battery percentage (0-100)
• isCharging (boolean) - whether the battery is charging
• currentCapacity (number) - current capacity (mAh)
• maxCapacity (number) - maximum capacity (mAh)
• cycleCount (number, optional) - charge cycle count
• health (number, optional) - battery health percentage (0-100)
• temperature (number, optional) - battery temperature (Celsius)

local bat = app.power.battery()
if bat then
    app.log.info("Level: " .. bat.level .. "%")
    app.log.info("Charging: " .. tostring(bat.isCharging))
    if bat.health then
        app.log.info("Health: " .. string.format("%.1f%%", bat.health))
    end
else
    app.log.info("No battery (desktop Mac)")
end

app.power.isOnAC()

Check if using external power.

Returns: boolean

if app.power.isOnAC() then
    app.log.info("On AC power")
end

app.power.timeRemaining()

Get remaining battery time.

Returns: number - remaining minutes

• -1 = calculating
• -2 = on AC power

local time = app.power.timeRemaining()
if time > 0 then
    app.log.info(math.floor(time) .. " minutes remaining")
elseif time == -1 then
    app.log.info("Estimating...")
end

app.power.thermalState()

Get system thermal state.

Returns: string - "nominal", "fair", "serious", "critical", "unknown"

local state = app.power.thermalState()  -- "nominal"

app.power.uptime()

Get system uptime.

Returns: number - seconds

local up = app.power.uptime()
local hours = math.floor(up / 3600)
local mins = math.floor((up % 3600) / 60)
app.log.info("Uptime: " .. hours .. " hours " .. mins .. " minutes")

Event Watching

app.power.watch(event, callback)

Watch for power source change events.

Parameters:

• event (string) - event name (currently only "powerSourceChanged" is supported)
• callback (function) - callback function, receives an event table:
  • isOnAC (boolean) - whether the Mac is on AC power
  • batteryLevel (number) - current battery percentage (0-100), or -1 if no battery

Returns: string, error - watcher handle ID

app.power.watch("powerSourceChanged", function(e)
    if e.isOnAC then
        app.log.info("Switched to AC power")
    else
        app.log.info("On battery, level: " .. e.batteryLevel .. "%")
    end
end)

app.power.stopAllWatchers()

Stop all power event watchers registered by the current plugin.

Returns: boolean

app.power.stopAllWatchers()

app.power.listWatchers()

List all power event watchers registered by the current plugin.

Returns: array<table> - each item contains:

• id (string) - watcher handle ID
• event (string) - event name being watched

local watchers = app.power.listWatchers()
for _, w in ipairs(watchers) do
    app.log.info(w.id .. " -> " .. w.event)
end

Examples

Battery Status Report

function MyPlugin:handleBatteryReport(context)
    local bat = app.power.battery()
    if not bat then
        app.dialog.alert("Battery", "This device has no battery")
        return
    end

    local info = string.format(
        "Level: %.0f%%\nCharging: %s\nCycles: %s\nHealth: %s\nTemperature: %s\nRemaining: %s",
        bat.level,
        bat.isCharging and "Yes" or "No",
        bat.cycleCount and tostring(bat.cycleCount) or "N/A",
        bat.health and string.format("%.1f%%", bat.health) or "N/A",
        bat.temperature and string.format("%.1f°C", bat.temperature) or "N/A",
        app.power.timeRemaining() > 0
            and math.floor(app.power.timeRemaining()) .. " minutes"
            or "On AC power"
    )

    app.dialog.alert("Battery Status", info)
end