app.notification - System Notification API

Send macOS system notifications.

Methods

app.notification.show(title, message)

Displays a system notification.

Parameters:

• title (string) - Notification title
• message (string) - Notification content

Returns: boolean - Whether successful

app.notification.show("Done", "File processing complete")

Notification Observation (requires notification.observe permission)

Cross-process notifications for monitoring system and other application notifications.

app.notification.observe(name, callback)

Observes distributed notifications.

Parameters:

• name (string) - Notification name
• callback (function) - Callback function function(name, userInfo?)

Returns: string, error - Observer ID (used to unobserve)

local id, err = app.notification.observe("com.example.dataChanged", function(name, info)
    app.log.info("Received notification: " .. name)
    if info and info.count then
        app.log.info("Data count: " .. info.count)
    end
end)

app.notification.unobserve(id)

Stops observing a notification.

Parameters:

• id (string) - Observer ID returned by observe

Returns: boolean, error

local ok, err = app.notification.unobserve(observerId)

app.notification.unobserveAll()

Stops observing all notifications.

Returns: boolean

app.notification.unobserveAll()

app.notification.post(name, userInfo?)

Posts a distributed notification (cross-process).

Parameters:

• name (string) - Notification name
• userInfo (table, optional) - Additional data (supports string/number/boolean/table)

Returns: boolean, error

app.notification.post("com.example.dataChanged", {
    count = 42,
    source = "MyPlugin"
})

Examples

Operation Complete Notification

function MyPlugin:handleConvert(context)
    local files = context.selectedFiles
    local success = 0

    for _, file in ipairs(files) do
        if self:convertFile(file) then
            success = success + 1
        end
    end

    app.notification.show("Conversion Complete", "Successfully converted " .. success .. "/" .. #files .. " files")
end

Error Notification

function MyPlugin:handleUpload(context)
    local ok, err = self:uploadFiles(context.selectedFiles)

    if ok then
        app.notification.show("Upload Successful", "Files uploaded to server")
    else
        app.notification.show("Upload Failed", err or "Unknown error")
    end
end

Cross-Plugin Communication

-- Plugin A: Post notification
function PluginA:handleSendData(context)
    local data = self:processFiles(context.selectedFiles)
    app.notification.post("com.myplugin.dataReady", {
        result = data,
        timestamp = os.time()
    })
end

-- Plugin B: Observe notification
function PluginB:init()
    self.observerId = app.notification.observe("com.myplugin.dataReady", function(name, info)
        if info and info.result then
            self:handleReceivedData(info.result)
        end
    end)
end

function PluginB:cleanup()
    if self.observerId then
        app.notification.unobserve(self.observerId)
    end
end

Notes

1. Permission: Notification permission is requested automatically by the app, plugins don’t need to handle it
2. Frequency: Avoid sending a large number of notifications in a short time
3. Content: Overly long titles and content will be truncated
4. Observer limit: Each plugin can register up to 50 observers
5. Permission separation: show is L0 (always available), observe/unobserve/post is L1 (requires notification.observe declaration in manifest)
6. Cross-process: userInfo only supports basic types (string/number/boolean/table)