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 any 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 any functions.

HPR.extensionName = "My Custom HPR Extension"

Type: table (array of strings)

Configures the array of supported HPR application versions for the loaded extension. This must be defined at the top level of your extension's script outside of any function blocks. Version strings are automatically normalized (leading v or V prefixes are stripped).

HPR.versionSupport = {"0.9.7", "0.9.8", "0.9.5"}

Type: boolean (property)

Configures whether API functions must be prefixed with HPR.. If set to false, API functions are registered to both the HPR namespace and the global environment namespace, allowing direct calling (e.g. log() instead of HPR.log()). Defaults to true.

HPR.useHPRTablePrefix = false

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()
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(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("MyExtension", "Initialized and active.")

Parameters: key: string — Returns: string

Retrieves the raw string value of a system configuration setting from HPR. Returns an empty string "" if the key does not exist.

local hwAccel = HPR.getSystemConfig("hardware-acceleration")
print("Hardware Accel: " .. hwAccel) -- e.g. "true" or "false"

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("config.csv", "enabled")
-- Read whole file as a key-value dictionary
local data = HPR.readCsv("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("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("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 and getExtensionPath) reference the exact same underlying function.

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

Parameters: None — Returns: table (list of available theme names)

Returns a Lua list containing the names of all themes currently registered or available in HPR.

local themes = HPR.getThemeNames()
for _, themeName in ipairs(themes) do
    print("Available theme: " .. themeName)
end

Parameters: None — Returns: string (name of the active theme)

Retrieves the name of the theme currently selected and active in the system settings.

local activeTheme = HPR.getCurrentThemeName()
print("Currently active theme: " .. activeTheme)

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()
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()
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()
for i, ext in ipairs(plugins) do
    print("Loaded extension: " .. ext.extensionName .. " by " .. ext.authorName)
end

Returns: boolean

Returns true if the current extension is determined to be compatible with the running version of HPR (i.e. the current HPR version is present in the extension's top-level HPR.versionSupport table), or false if it is incompatible or missing version support.

if not HPR.amICompatible() then
    print("Warning: Running extension on an untested HPR version!")
end

Parameters: authorName: string, extensionName: string — Returns: nothing

Unloads an active extension by matching its author and extension names.

HPR.unloadExtension("Plexescor", "My Custom HPR Extension")

Parameters: authorName: string, extensionName: string — Returns: nothing

Reloads an active extension by matching its author and extension names, triggering its initialization sequence again.

HPR.reloadExtension("Plexescor", "My Custom HPR Extension")

Parameters: None — Returns: nothing

Asynchronously triggers a full reload of the calling extension after a short 50ms delay, allowing an extension to safely re-initialize itself without hanging its own execution thread.

HPR.reloadMyself()

Parameters: None — Returns: nothing

Scans the extensions directory for new, updated, or removed extensions, dynamically syncing the application's extension state.

HPR.refreshExtensions()

Parameters: None — Returns: string (relative path)

Returns the relative directory path of the running extension relative to HPR's root extension directory (ending with a trailing slash). Returns an empty string "" if the extension file resides directly in the root extensions folder.

local relDir = HPR.getExtensionDir()
print("Relative extension dir: " .. relDir)

Parameters: None — Returns: string (full absolute directory path)

Returns the full canonical absolute filesystem directory path of the running extension (ending with a trailing / or \). Recommended when constructing absolute paths for loading native shared libraries via package.loadlib() or accessing external files.

local absDir = HPR.getExtensionAbsoluteDir()
print("Absolute extension dir: " .. absDir)

Parameters: bool: boolean — Returns: nothing

Dynamically configures whether API functions must be prefixed with HPR. at runtime. If toggled to false, API functions are instantly exposed globally.

HPR.setUseHPRTablePrefix(false)

Parameters: bool: boolean — Returns: nothing

Dynamically configures whether HPR API functions require the legacy _E suffix (e.g. writeCsv_E) at runtime.

HPR.setLegacyAPISuffix(true)

Parameters: versions: table (array of version strings) — Returns: nothing

Dynamically configures the list of supported HPR application versions at runtime, instantly re-triggering the application's compatibility check logic.

HPR.setVersionSupport({"0.9.8", "0.9.7"})

Parameters: (name, matchesEnvironment, initialize, 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(
        "MyCompositor",
        function(env) return env:find("MyCompositor") ~= nil end,
        function() print("Loaded!") 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("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("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("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([[
    create table if not exists my_data (
        key text unique,
        value text
    );
]])

-- Insert with parameterized values
HPR.dbExecute(
    "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("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()
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("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()
local today_str = HPR.convertToDate_DDMMYY(today_ms)
local dbPath = HPR.getDbPathForDate(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("28-05-26")
local rows = HPR.dbQueryPath(path, "select name, duration from app_usage;")

Parameters: days: int (number of past days to query), mode: string ("total", "average", or "raw"), sql: string, params: table (optional) — Returns: table (array of row tables)

Queries multiple daily database files across the last days days starting from today.

Under the Hood (Parallel Execution): To keep performance extremely fast and optimized, this function spawns a pool of parallel background worker threads (one thread per daily database file). Each thread opens its day's database, executes the SQL query concurrently, and writes the results to a thread-safe memory index before joining back.

The results are aggregated and merged synchronously before returning to Lua:

• If mode is "total", values in the "duration" column are summed up across all days (grouped by the other returned columns).
• If mode is "average", values in the "duration" column are averaged by dividing the sum by the count of days that specific grouped record was actively tracked.
• If mode is anything else (e.g. "raw"), no daily aggregation is performed; instead, a flat list of rows is returned exactly as each day's query produced them, with no extra columns injected.

-- Get total duration of app usage over the last 7 days
local rows = HPR.dbQueryNumber(
    7,
    "total",
    "select name, duration from app_usage;"
)

Parameters: dateFrom: string ("DD-MM-YY"), dateTo: string ("DD-MM-YY"), mode: string ("total", "average", or "raw"), sql: string, params: table (optional) — Returns: table (array of row tables)

Queries multiple daily database files within a specific date range. Like the number query, it executes queries concurrently using a pool of parallel worker threads (one thread per day).

Date Order-Reversal: Under the hood, this function automatically detects and handles reversed date inputs. If the start date is chronologically after the end date, HPR swaps them before execution so the query succeeds seamlessly.

Integrates the same mode aggregation logic ("total", "average", or "raw") and blocks the calling Lua thread for up to 7500ms while this query's parallel workers complete, returning an empty table if they don't finish in time.

local rows = HPR.dbQueryRange(
    "01-06-26", 
    "07-06-26", 
    "average", 
    "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("windowName_S", "firefox")

-- Set an array of structs (each struct maps to a Slint struct)
HPR.setUiProperty("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("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(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.

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.

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.

To build a compatible module, compile it with the extern "C" entrypoint. This entrypoint is executed when the library is loaded and returns the module table or registers global functions.

// mylib.cpp (Vanilla C++)
#include <lua.hpp>
#include <iostream>

// The native function called from Lua
static int l_hello(lua_State* L) {
    std::cout << "Yo i am native" << std::endl;
    return 0;
}

// Entry point called by Lua's package loader
extern "C" int luaopen_mylib(lua_State* L) {
    lua_register(L, "hello", l_hello); // Registers function globally
    return 0;
}

Compile the library:

g++ -shared -fPIC -o mylib.so mylib.cpp

Then, load and run it inside your extension:

-- main.lua
local extDir = HPR.getExtensionAbsoluteDir()
local dllPath = (HPR.getOsName() == "Windows") and (extDir .. "mylib.dll") or (extDir .. "mylib.so")

local loader, err = package.loadlib(dllPath, "luaopen_mylib")
if loader then
    loader() -- Runs luaopen_mylib to register global function
    hello()  -- Prints: Yo i am native
else
    HPR.log("MyExtension", "Failed to load native library: " .. tostring(err))
end

C Signature: extern "C" HPR_API void HPR_invokeOnSlintThread(void(*fn)(void*), void* userdata);

Why use it: Slint UI components, windowing, and property bindings are thread-bound and must strictly execute on Slint's main event loop thread. When writing compiled C/C++ extensions (`.so` on Linux / `.dll` on Windows) loaded via Lua, attempting to construct UI instances or mutate Slint values from background worker threads causes thread assertions or application crashes. HPR_invokeOnSlintThread safely dispatches arbitrary C/C++ callbacks to run directly on the Slint main thread loop.

How to use it: Dynamically resolve HPR_invokeOnSlintThread using GetProcAddress (Windows) or dlsym (Linux). Pass a static callback function pointer void(*)(void*) and payload context pointer void*. Use std::promise and std::future if the calling thread needs to block until main-thread execution finishes.

The code snippet below is adapted from the official HPR-Store repository (src/library.cpp):

// Example from HPR-Store: https://github.com/plexescor/HPR-Store
typedef void (*SlintInvokeFn)(void (*)(void *), void *);

static SlintInvokeFn g_hprInvoke = nullptr;

extern "C" HPR_EXPORT void initialize(lua_State *L) {
    // Dynamically resolve the export symbol from HPR host executable
#ifdef _WIN32
    HMODULE hpr = GetModuleHandleA(nullptr);
    g_hprInvoke = (SlintInvokeFn)GetProcAddress(hpr, "HPR_invokeOnSlintThread");
#else
    g_hprInvoke = (SlintInvokeFn)dlsym(RTLD_DEFAULT, "HPR_invokeOnSlintThread");
#endif

    if (!g_hprInvoke) return;

    struct InitData { std::promise<void> *ready; };
    auto data = new InitData{ new std::promise<void>() };
    auto fut = data->ready->get_future();

    // Safely dispatch UI creation to Slint event loop thread
    g_hprInvoke([](void *ud) {
        auto d = static_cast<InitData *>(ud);
        gui = std::make_unique<GUI>();
        d->ready->set_value();
        delete d->ready;
        delete d;
    }, data);

    fut.wait(); // Block caller until main-thread Slint GUI init completes
}