Raw Extension API Reference

Type: string (property)

Configures the author or developer name of the loaded extension. This must be defined at the top level of your extension's script (outside of init() or any other lifecycle functions).

HPR.authorName = "Plexescor"

Type: string (property)

Configures the custom display name of the loaded extension. This must be defined at the top level of your extension's script (outside of init() or any other lifecycle functions).

HPR.extensionName = "My Custom HPR Extension"

Returns: uint64 (Unix timestamp in milliseconds)

Returns the current system time as a Unix timestamp in milliseconds. Useful for timestamping events, measuring elapsed durations, or seeding time-series database entries.

local now = HPR.getTime_MS_E()
print("Current time (ms): " .. now)

Parameters: ms: int (milliseconds) — Returns: nothing

Blocks the calling extension's background thread for the specified number of milliseconds. Since every extension runs on its own isolated OS thread, this only pauses your script — HPR and all other extensions remain fully responsive. Useful for rate-limiting inside a callback or performing a one-shot delayed action without restructuring your tick loop.

HPR.sleep_E(2000) -- pause this extension thread for 2 seconds

Parameters: name: string (log category/prefix), message: string (content to log) — Returns: nothing

Appends a formatted message to HPR's centralized logger. The log will automatically include the category prefix specified in the name argument, appearing as [name] message. This is highly recommended over standard Lua print statements for structured, traceable debugging output in production environments.

HPR.log_E("MyExtension", "Initialized and active.")

Parameters: path: string (path relative to the root of the extensions directory, not the individual extension subdirectory), key: string|number|boolean (optional) — Returns: string|number|boolean (if key requested) OR table (key-value dictionary mapping if key omitted)

Reads and parses a CSV file located in HPR's designated extension directory (e.g. ~/.config/HPR/extensions/). Note that the path argument is resolved relative to the global extensions directory root itself, not the specific extension's subdirectory. Absolute paths or parent traversals (like ../) are blocked for security. If a specific key is requested, returns the parsed value for that key, automatically converting boolean text ("true"/"false") and literal numbers into Lua types, and trimming whitespace for them. If the file read fails or is denied access, an empty string "" is returned. If the key is omitted, it returns a single Lua table (dictionary) mapping all keys directly to their corresponding parsed values (e.g., { ["usershit"] = true, ["enabled"] = false }).

-- Read specific key
local val = HPR.readCsv_E("config.csv", "enabled")
-- Read whole file as a key-value dictionary
local data = HPR.readCsv_E("config.csv")
for key, value in pairs(data) do
    print(key .. ": " .. tostring(value))
end

Parameters: path: string (path relative to the root of the extensions directory, not the individual extension subdirectory), key: string|number|boolean, value: string|number|boolean — Returns: boolean (success status)

Writes or updates a key-value entry in the specified CSV file. Note that the path argument is resolved relative to the global extensions directory root itself, not the specific extension's subdirectory. Nothing is quoted in the CSV file, even strings. Automatically creates necessary subdirectories if requested. If the key already exists in the file, it performs an in-place update (upsert) to preserve the rest of the CSV entries. Returns true on success, or false on failure or access denial (printing standard error to std::cerr).

local ok = HPR.writeCsv_E("settings/general.csv", "volume", 95)

Parameters: path: string (path relative to the root of the extensions directory, not the individual extension subdirectory) — Returns: boolean (true if the file was deleted successfully, false otherwise)

Deletes the specified CSV file. Note that the path argument is resolved relative to the global extensions directory root itself, not the specific extension's subdirectory.

Note on Shared Workspace Design: Please be aware that the extensions workspace is a shared environment. It operates essentially as a collaborative "wild west" by design, allowing any extension to read, modify, or delete database and configuration files created by any other extension to foster deep script integration and open data exchanges.

local deleted = HPR.deleteCsv_E("settings/general.csv")
if deleted then
    print("CSV successfully removed!")
end

Parameters: None — Returns: string (the relative path from the extensions root of the calling extension's subdirectory with a trailing separator)

Returns a string containing the relative path from HPR's global extensions directory root to the calling extension's own subdirectory, falling back to an empty string if the script resides directly at the extensions root folder. Both names (getExtensionDir_E and getExtensionPath_E) reference the exact same underlying function.

-- Get the relative folder path of this specific extension
local myFolder = HPR.getExtensionDir_E()
-- Seamlessly resolve settings.csv relative to your own subfolder
local settings = HPR.readCsv_E(myFolder .. "settings.csv")

Returns: nothing

Forces the background pattern analyzer to calculate fresh, up-to-date insight reports based on current session and database logs.

Returns: string

Returns the process name or window title of the most heavily used application in the active analysis window.

Returns: string

Returns a user-friendly formatted duration representing the total amount of tracked focus time.

Returns: string

Returns the total count of context/application switches.

Returns: string

Returns the details of the longest uninterrupted focus session.

Returns: string

Returns the specific hour of the day where the user showed maximum active productive engagement.

Returns: string

Returns the application class name from which the user switched away most frequently during active tracking.

Returns: string

Returns the application class name to which the user switched most frequently during active tracking.

Returns: string (e.g. "Linux" or "Windows")

Returns the operating system name HPR is currently running on.

local os = HPR.getOsName_E()
print("Current OS: " .. os)

Returns: string (e.g. "Hyprland", "Kde", or "")

Returns the specific desktop compositor or environment HPR is actively using to poll windows if running on Linux. On Windows systems, this function returns an empty string "".

local comp = HPR.getEnvironmentName_E()
print("Compositor: " .. comp)

Returns: table (array of loaded extension tables)

Returns an array of all loaded extensions in HPR. Each element in the returned table is a key-value dictionary representing an active extension, containing its authorName and extensionName properties. Useful for discovery, verification, and inter-extension dependencies.

local plugins = HPR.getLoadedExtensions_E()
for i, ext in ipairs(plugins) do
    print("Loaded extension: " .. ext.extensionName .. " by " .. ext.authorName)
end

Parameters: (name, matchesEnvironment, initialize, isUsable, getCurrentWindow, getCurrentTitle, getCurrentPid)

Registers a completely new custom tracking backend dynamically. HPR's backend manager calls the registered functions during startup to inspect compositors and get current window classes, titles, and process IDs. For a detailed guide on using this, please consult the Custom Backend Tutorial.

function init()
    HPR.registerBackend_E(
        "MyCompositor",
        function(env) return env:find("MyCompositor") ~= nil end,
        function() print("Loaded!") end,
        function() return true end,
        function() return "browser" end,
        function() return "Home Page" end,
        function() return "1234" end
    )
end

Parameters: eventName: string, callback: function — Returns: int (subscription ID)

Subscribes a Lua callback function to a system or custom named event. Whenever the event is emitted, your callback will run. Returns a unique subscription ID integer that must be saved to disconnect later.

local subId = HPR.connect_E("WINDOW_CHANGED", function(data)
    print("Active window class changed to: " .. data.toWindow)
end)

Parameters: eventName: string, data: table (optional) — Returns: nothing

Broadcasts a named signal to the Event Hub, triggering all active callbacks connected to this event name. You can optionally pass a Lua table/value containing a custom payload structure.

HPR.emit_E("my_custom_alarm", { temp = 82.5, warning = true })

Parameters: eventName: string, subscriptionId: int — Returns: nothing

Unsubscribes a specific listener using its unique subscription ID. Calling this manually inside onExit() is supported for precise runtime lifecycle management, but is no longer required for basic memory safety.

function onExit()
    HPR.disconnect_E("MIDNIGHT_ROLLOVER", subId)
end

Parameters: sql: string, params: table (optional) — Returns: nothing

Executes a write SQL statement (CREATE, INSERT, UPDATE, DELETE) against HPR's SQLite database. The optional second argument is a Lua table of strings bound to ? placeholders in the SQL query, preventing SQL injection. Always use parameterized queries when inserting user-derived data.

-- Create a table
HPR.dbExecute_E([[
    create table if not exists my_data (
        key text unique,
        value text
    );
]])

-- Insert with parameterized values
HPR.dbExecute_E(
    "insert or replace into my_data (key, value) values (?, ?);",
    { "active_app", "firefox" }
)

Parameters: sql: string, params: table (optional) — Returns: table (array of row tables)

Executes a read SQL statement (SELECT) and returns the results as a Lua table. Each element in the returned table is a row, represented as a Lua table with column names as keys.

local rows = HPR.dbQuery_E("select key, value from my_data;")

for i, row in ipairs(rows) do
    print(row.key .. " = " .. row.value)
end

Parameters: none — Returns: string (full absolute file path)

Returns the absolute, resolved filesystem path of the currently loaded historical database. Returns an empty string if HPR is currently in live-tracking mode.

local histPath = HPR.getLoadedHistDbPath_E()
print("Loaded past DB path: " .. histPath)

Parameters: sql: string, params: table (optional) — Returns: table (array of rows)

Executes a read SQL query against the currently active historical database file (set during a "LOAD_DATABASE_SINGULAR" calendar switch). This is a safe, high-level helper that completely abstracts database opening, folder traversal, and closing operations. Blocks for up to 5 seconds waiting for the async historical DB load to complete before running the query.

local rows = HPR.dbQueryHistorical_E("select song_name from spotify_songs;")

Parameters: date: string (e.g. "30-05-26") — Returns: string (full absolute file path)

Resolves a given date string into its corresponding absolute database file path on the system. Excellent for locating specific days to query in an isolated context.

-- Dynamically resolve today's path
local today_ms = HPR.getTime_MS_E()
local today_str = HPR.convertToDate_DDMMYY_E(today_ms)
local dbPath = HPR.getDbPathForDate_E(today_str)
print(dbPath)

Parameters: dbPath: string, sql: string, params: table (optional) — Returns: table (array of row tables)

Executes a SELECT query directly against a specific database file path in a completely isolated context. It returns the query results directly as a native Lua table without affecting HPR's main application state or active GUI charts.

local path = HPR.getDbPathForDate_E("28-05-26")
local rows = HPR.dbQueryPath_E(path, "select name, duration from app_usage;")

Parameters: name: string, value: any — Returns: nothing

Sets a named property on the root Slint UI component. The property name must exactly match an in property defined in app-window.slint. HPR converts the Lua value to a C++ intermediate on the extension thread, then dispatches the Slint update to the main UI thread. Supported types: string, number, boolean, table (array → Slint model, key-value → Slint struct). If the UI is not yet loaded, the call is silently ignored.

-- Set a simple string property
HPR.setUiProperty_E("windowName_S", "firefox")

-- Set an array of structs (each struct maps to a Slint struct)
HPR.setUiProperty_E("spotifySongs_S", {
    { name = "Song A", artist = "Artist 1", duration = "01:23:45", duration_i = 5025000 },
    { name = "Song B", artist = "Artist 2", duration = "00:45:30", duration_i = 2730000 },
})

Parameters: name: string, luaFunction: function(...any) — Returns: nothing (registers the handler)

Registers a Lua function as a handler for a Slint callback. When the named callback is triggered from the Slint UI (e.g. clicking a row or a button), HPR invokes your Lua function.

Argument Forwarding: As implemented in the C++ extension manager, the callback lambda intercepts the arguments passed from the Slint UI (auto args), converts each from its Slint type to C++ and then to Lua objects, and forwards all of them as positional parameters directly to your Lua function.

Return Behavior: The C++ handler is defined with a void/empty return (return slint::interpreter::Value();). Any values returned by your Lua callback function are ignored, meaning the callback bridge is strictly one-way (parameter-only forwarding from Slint to Lua).

The callback name must exactly match a callback defined in the Slint component. If the UI is not yet loaded, the call is silently ignored.

HPR.registerUiCallback_E("songRowClicked", function(songData)
    print("User clicked song: " .. tostring(songData.name) .. " by " .. tostring(songData.artist))
end)

Parameters: ms: int (milliseconds) — Returns: string

Converts a duration in milliseconds to a human-readable "HH:MM:SS" formatted string. Commonly used for displaying tracked time in the UI.

local formatted = HPR.formatTime_HHMMSS_E(5025000)
print(formatted) -- "01:23:45"

Parameters: ms: int (Unix timestamp in ms) — Returns: string

Converts a Unix timestamp in milliseconds to a date string in "DD-MM-YY" format.

Parameters: ms: int (Unix timestamp in ms) — Returns: string

Converts a Unix timestamp in milliseconds to a date string in "MM-YY" format (month and year only).

Parameters: ms: int (Unix timestamp in ms) — Returns: string

Converts a Unix timestamp in milliseconds to a 12-hour time string in "HH:MM:SS AM/PM" format.

Parameters: dateStr: string ("DD-MM-YY") — Returns: int (Unix timestamp in ms)

Parses a "DD-MM-YY" date string and returns the corresponding Unix timestamp in milliseconds. The inverse of convertToDate_DDMMYY_E.

Parameters: dateStr: string ("MM-YY") — Returns: int (Unix timestamp in ms)

Parses a "MM-YY" date string and returns the corresponding Unix timestamp in milliseconds. The inverse of convertToDate_MMYY_E.

Parameters: dateStr: string ("DD-MM-YY") — Returns: string ("MM-YY")

Extracts the month-year portion from a full "DD-MM-YY" date string, returning just "MM-YY". Useful for grouping daily records by month.