Plugin API Reference
Complete reference for all APIs available to mahpastes plugins.
clips
Manage clipboard entries.
clips.list(filter?)
Returns an array of clips without the data field (for performance).
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| filter | table | No | Optional filter criteria |
| filter.content_type | string | No | Filter by MIME type (e.g., "image/png") |
| filter.limit | number | No | Max results (default: 100, max: 1000) |
| filter.offset | number | No | Skip first N results (default: 0) |
Returns: Array of clip objects or nil, error_message
Clip object (list):
{
id = 123,
content_type = "image/png",
filename = "screenshot.png",
created_at = 1704067200, -- Unix timestamp
is_archived = false
}
Example:
-- Get all clips
local clips = clips.list()
-- Get only images
local images = clips.list({ content_type = "image/png" })
-- Paginate results
local page2 = clips.list({ limit = 10, offset = 10 })
clips.get(id)
Returns a single clip with its data.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| id | number | Yes | Clip ID |
Returns: Clip object with data, or nil if not found, or nil, error_message
Clip object (get):
{
id = 123,
content_type = "text/plain",
filename = "note.txt",
created_at = 1704067200,
is_archived = false,
data = "Hello, world!", -- Text content as string
data_encoding = nil -- nil for text content
}
-- For binary content (images, etc.):
{
id = 124,
content_type = "image/png",
filename = "screenshot.png",
created_at = 1704067200,
is_archived = false,
data = "iVBORw0KGgo...", -- Base64-encoded binary
data_encoding = "base64" -- Indicates encoding
}
Example:
local clip = clips.get(123)
if clip then
if clip.data_encoding == "base64" then
local binary = base64.decode(clip.data)
-- Process binary data
else
-- Text content, use directly
log("Content: " .. clip.data)
end
end
clips.create(options)
Creates a new clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| options | table | Yes | Clip creation options |
| options.data | string | Yes | Content (text or base64 for binary) |
| options.content_type | string | No | MIME type (default: "application/octet-stream") |
| options.filename | string | No | Optional filename |
| options.data_encoding | string | No | Set to "base64" for binary data |
Returns: Table with id field (e.g., {id = 123}), or nil, error_message
Size limit: 50MB maximum for clip data.
Example:
-- Create text clip
local result = clips.create({
data = "Hello, world!",
content_type = "text/plain",
filename = "greeting.txt"
})
if result then
log("Created clip with ID: " .. result.id)
end
-- Create image clip from base64
local result = clips.create({
data = base64_image_data,
data_encoding = "base64",
content_type = "image/png",
filename = "generated.png"
})
clips.get_data(id)
Returns raw clip data without metadata. For text content, returns the data as-is. For binary content, returns base64-encoded data.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| id | number | Yes | Clip ID |
Returns: data, content_type on success, or nil, error_message
Example:
local data, mime_type = clips.get_data(123)
if data then
log("Content type: " .. mime_type)
-- For binary content, data is base64-encoded
-- For text content, data is plain text
end
clips.create_from_url(url, options?)
Downloads content from a URL and creates a new clip. The URL domain must be in the plugin's network permissions. Redirects are validated against the same domain allowlist.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | URL to download (must be http:// or https://) |
| options | table | No | Optional settings |
| options.filename | string | No | Override filename (also accepts name) |
| options.content_type | string | No | Override MIME type (also accepts mime_type) |
Returns: Table with id field (e.g., {id = 123}), or nil, error_message
Size limit: 50MB maximum download size.
Example:
local result, err = clips.create_from_url("https://example.com/image.png", {
name = "downloaded.png"
})
if result then
log("Created clip: " .. result.id)
else
log("Error: " .. err)
end
clips.update(id, options)
Updates a clip's properties.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| id | number | Yes | Clip ID |
| options | table | Yes | Fields to update |
| options.is_archived | boolean | No | Archive status |
Returns: true on success, or false, error_message
Example:
-- Archive a clip
clips.update(123, { is_archived = true })
clips.delete(id)
Permanently deletes a clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| id | number | Yes | Clip ID |
Returns: true on success, or false, error_message
Example:
clips.delete(123)
clips.delete_many(ids)
Deletes multiple clips at once.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| ids | table | Yes | Array of clip IDs |
Returns: true on success, or false, error_message
Example:
clips.delete_many({123, 124, 125})
clips.archive(id)
Archives a clip (shorthand for update with is_archived = true).
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| id | number | Yes | Clip ID |
Returns: true on success, or false, error_message
clips.unarchive(id)
Unarchives a clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| id | number | Yes | Clip ID |
Returns: true on success, or false, error_message
tags
Manage tags and clip-tag associations.
tags.list()
Returns all tags with usage counts.
Returns: Array of tag objects, or nil, error_message
Tag object:
{
id = 1,
name = "screenshot",
color = "#3B82F6",
count = 15 -- Number of clips with this tag
}
Example:
local all_tags = tags.list()
for _, tag in ipairs(all_tags) do
log(tag.name .. ": " .. tag.count .. " clips")
end
tags.get(id)
Returns a single tag by ID.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| id | number | Yes | Tag ID |
Returns: Tag object, or nil if not found, or nil, error_message
tags.create(name)
Creates a new tag. Color is automatically assigned from a rotating palette.
If the name contains / separators, intermediate parent tags are auto-created. For example, tags.create("work/client1/projectABC") creates work, work/client1, and work/client1/projectABC (skipping any that already exist). The returned tag object is the leaf tag.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Tag name (max 50 characters). Use / to create subtags. |
Returns: New tag object (the leaf tag), or nil, error_message
Example:
local tag, err = tags.create("important")
if tag then
log("Created tag with ID: " .. tag.id)
else
log("Error: " .. err)
end
-- Create a subtag hierarchy
local subtag = tags.create("work/client1/projectABC")
-- Also creates "work" and "work/client1" if they don't exist
tags.update(id, options)
Updates a tag's name or color.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| id | number | Yes | Tag ID |
| options | table | Yes | Fields to update |
| options.name | string | No | New tag name |
| options.color | string | No | New color (hex format, e.g., "#FF0000") |
Returns: true on success, or false, error_message
Example:
tags.update(1, { name = "urgent", color = "#EF4444" })
tags.delete(id)
Deletes a tag. Removes the tag from all clips.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| id | number | Yes | Tag ID |
Returns: true on success, or false, error_message
tags.add_to_clip(tag_id, clip_id)
Adds a tag to a clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| tag_id | number | Yes | Tag ID |
| clip_id | number | Yes | Clip ID |
Returns: true on success, or false, error_message
Example:
-- Auto-tag a clip based on content type
function on_clip_created(data)
local clip = clips.get(data.id)
if clip.content_type:find("image/") then
local tag = find_or_create_tag("screenshot")
tags.add_to_clip(tag.id, clip.id)
end
end
tags.remove_from_clip(tag_id, clip_id)
Removes a tag from a clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| tag_id | number | Yes | Tag ID |
| clip_id | number | Yes | Clip ID |
Returns: true on success, or false, error_message
tags.get_for_clip(clip_id)
Returns all tags for a specific clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Clip ID |
Returns: Array of tag objects, or nil, error_message
Example:
local clip_tags = tags.get_for_clip(123)
for _, tag in ipairs(clip_tags) do
log("Tag: " .. tag.name)
end
storage
Plugin-scoped key-value storage. Each plugin has isolated storage that persists across restarts.
storage.get(key)
Retrieves a stored value.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| key | string | Yes | Storage key |
Returns: Stored value as string, or nil if not found
Example:
local last_sync = storage.get("last_sync_time")
if last_sync then
log("Last synced: " .. last_sync)
end
storage.set(key, value)
Stores a value. Overwrites existing value if key exists.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| key | string | Yes | Storage key |
| value | string | Yes | Value to store |
Returns: true on success, or false, error_message
Example:
-- Store a simple value
storage.set("counter", "42")
-- Store complex data as JSON
local config = { enabled = true, threshold = 100 }
storage.set("config", json.encode(config))
storage.delete(key)
Deletes a stored value.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| key | string | Yes | Storage key |
Returns: true on success, false on error
storage.list()
Lists all storage keys for this plugin.
Returns: Array of key strings, or nil, error_message
Example:
local keys = storage.list()
for _, key in ipairs(keys) do
log("Key: " .. key)
end
http
Make HTTP requests to allowed domains. Plugins must declare domains in their manifest.
Domain Restrictions
HTTP requests are only allowed to domains listed in the plugin manifest:
Plugin = {
name = "My Plugin",
network = {
["api.example.com"] = {"GET", "POST"},
["webhook.site"] = {"POST"},
["*.cdn.example.com"] = {"GET"}, -- Wildcard subdomain
},
}
- Each domain must be explicitly declared
- Wildcard subdomains are supported (e.g.,
*.cdn.example.commatchesv1.cdn.example.com) - Allowed HTTP methods must be specified per domain
- Redirects are validated: each hop is checked against the domain allowlist, and HTTPS is enforced
- Request timeout: 5 minutes
- Max response size: 50MB
- Rate limit: 100 requests per minute
http.get(url, options?)
Performs a GET request.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | Full URL (must be to allowed domain) |
| options | table | No | Request options |
| options.headers | table | No | Request headers as key-value pairs |
Returns: Response object, or nil, error_message
Response object:
{
status = 200, -- HTTP status code
headers = { -- Response headers
["Content-Type"] = "application/json",
["X-Custom"] = "value"
},
body = "..." -- Response body as string
}
Example:
local resp, err = http.get("https://api.example.com/data", {
headers = {
["Authorization"] = "Bearer " .. api_key
}
})
if resp then
if resp.status == 200 then
local data = json.decode(resp.body)
-- Process data
else
log("Error: HTTP " .. resp.status)
end
else
log("Request failed: " .. err)
end
http.post(url, options?)
Performs a POST request.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | Full URL |
| options | table | No | Request options |
| options.headers | table | No | Request headers |
| options.body | string | No | Request body |
Returns: Response object, or nil, error_message
Example:
local resp = http.post("https://api.example.com/upload", {
headers = {
["Content-Type"] = "application/json"
},
body = json.encode({ message = "Hello" })
})
http.put(url, options?)
Performs a PUT request. Same signature as http.post.
http.patch(url, options?)
Performs a PATCH request. Same signature as http.post.
http.delete(url, options?)
Performs a DELETE request.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | Full URL |
| options | table | No | Request options |
| options.headers | table | No | Request headers |
Returns: Response object, or nil, error_message
fs
Filesystem access with user permission prompts.
Permission Model
- Plugins must declare filesystem intent in their manifest
- First access to a path triggers a user approval dialog
- User can approve a directory (covers all files and subdirectories within)
- Approvals are stored in the database and remembered across restarts
fs.existsonly works within already-approved directories (no prompt, returns false for unapproved paths)- Rate limit: 50 filesystem operations per minute
Manifest declaration:
Plugin = {
name = "My Plugin",
filesystem = {
read = true, -- Request read access
write = true, -- Request write access
},
}
fs.read(path)
Reads a file's contents. Triggers permission prompt on first access to a directory.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| path | string | Yes | Absolute file path |
Returns: File contents as string, or nil, error_message
Size limit: 50MB maximum file size.
Example:
local content, err = fs.read("/Users/me/Documents/notes.txt")
if content then
log("File contents: " .. content)
else
log("Error: " .. err)
end
fs.write(path, content)
Writes content to a file. Creates parent directories if needed.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| path | string | Yes | Absolute file path |
| content | string | Yes | Content to write |
Returns: true on success, or false, error_message
Example:
local success = fs.write("/Users/me/Documents/backup.txt", "Backup content")
if success then
log("File written successfully")
end
fs.list(path)
Lists directory contents.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| path | string | Yes | Absolute directory path |
Returns: Array of file info objects, or nil, error_message
File info object:
{
name = "document.txt",
is_dir = false,
size = 1024, -- Size in bytes
modified = 1704067200 -- Unix timestamp
}
Example:
local files = fs.list("/Users/me/Documents")
if files then
for _, file in ipairs(files) do
if file.is_dir then
log("[DIR] " .. file.name)
else
log(file.name .. " (" .. file.size .. " bytes)")
end
end
end
fs.exists(path)
Checks if a path exists. Only works within already-approved directories (does not trigger a permission prompt).
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| path | string | Yes | Absolute path |
Returns: true if exists within approved path, false otherwise
Note: Returns false for paths outside approved directories to avoid leaking filesystem information.
toast
Display toast notifications to the user.
toast.show(message, type?)
Shows a toast notification.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| message | string | Yes | Notification message (max 200 characters) |
| type | string | No | Toast type: "info" (default), "success", or "error" |
Returns: true if shown, false if rate-limited
Rate limit: 5 toasts per minute per plugin.
While the mahpastes window is in the background and the user has turned on System Notifications, toasts are also shown as native notifications titled with the plugin's name (bursts are combined). Results reported with task.complete and task.fail notify the same way.
Example:
toast.show("Sync complete!", "success")
toast.show("Warning: File not found", "error")
toast.show("Processing...") -- defaults to "info"
task
Track progress of long-running operations. Tasks show a progress indicator in the UI.
task.start(name, total?)
Starts a new task and returns a task ID. Shows a progress bar in the UI.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Display name for the task |
| total | number | No | Total number of steps (default: 1). Used with task.progress to track completion. |
Returns: Task ID (number)
Example:
local task_id = task.start("Processing images", 5)
task.progress(task_id, current)
Updates a task's progress. The current value is an absolute count relative to the total passed to task.start.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| task_id | number | Yes | Task ID from task.start |
| current | number | Yes | Current step number (0 to total from task.start) |
Returns: true on success, or false, error_message
Example:
local task_id = task.start("Processing images", 5)
for i = 1, 5 do
-- Process item...
task.progress(task_id, i)
end
task.complete(task_id)
task.complete(task_id)
Marks a task as completed. Automatically sets progress to the total.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| task_id | number | Yes | Task ID from task.start |
Returns: true on success, or false, error_message
Example:
task.complete(task_id)
task.fail(task_id, error_message?)
Marks a task as failed.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| task_id | number | Yes | Task ID from task.start |
| error_message | string | No | Error description (default: "Unknown error") |
Returns: true on success, or false, error_message
Example:
task.fail(task_id, "API returned an error")
Tasks are automatically cleaned up 5 minutes after completion or failure.
Utility Functions
log(message)
Logs a message to the application log. Useful for debugging.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| message | string | Yes | Message to log |
Returns: Nothing
Example:
log("Plugin initialized")
log("Processing clip ID: " .. clip.id)
Logs appear as: [plugin:your-plugin-name] Your message
json.encode(table)
Encodes a Lua table to JSON string.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| table | table | Yes | Lua table to encode |
Returns: JSON string, or nil, error_message
Example:
local data = { name = "test", count = 42, enabled = true }
local json_str = json.encode(data)
-- Result: '{"name":"test","count":42,"enabled":true}'
Note: Arrays (tables with consecutive integer keys starting at 1) are encoded as JSON arrays. Other tables are encoded as JSON objects.
json.decode(string)
Decodes a JSON string to a Lua table.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| string | string | Yes | JSON string to decode |
Returns: Lua table, or nil, error_message
Example:
local data = json.decode('{"name":"test","count":42}')
log(data.name) -- "test"
log(data.count) -- 42
base64.encode(data)
Encodes a string to base64.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| data | string | Yes | Data to encode |
Returns: Base64-encoded string
Example:
local encoded = base64.encode("Hello, world!")
-- Result: "SGVsbG8sIHdvcmxkIQ=="
base64.decode(string)
Decodes a base64 string.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| string | string | Yes | Base64-encoded string |
Returns: Decoded string, or nil, error_message
Example:
local decoded = base64.decode("SGVsbG8sIHdvcmxkIQ==")
-- Result: "Hello, world!"
utils.time()
Returns the current Unix timestamp (seconds since epoch).
Returns: Number (Unix timestamp)
Example:
local now = utils.time()
log("Current timestamp: " .. now)
-- Store for later comparison
storage.set("last_run", tostring(now))
utils.sha256(data)
Returns the SHA-256 hex digest of a string.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| data | string | Yes | Data to hash |
Returns: Hex-encoded hash string
utils.hmac_sha256(key, data)
Returns the HMAC-SHA256 hex digest.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| key | string | Yes | HMAC key |
| data | string | Yes | Data to sign |
Returns: Hex-encoded HMAC string
utils.url_encode(s)
URL-encodes a string.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| s | string | Yes | String to encode |
Returns: URL-encoded string
utils.url_decode(s)
Decodes a URL-encoded string.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| s | string | Yes | String to decode |
Returns: Decoded string
utils.clipboard_write(text)
Writes text to the system clipboard.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | Yes | Text to copy |
Returns: true on success, or nil, error_message if clipboard access is not permitted or the clipboard could not be written (for example, a Linux session with no reachable clipboard, or a headless server with no display)
Requires clipboard = true in the plugin manifest.
metadata
Read and write key-value metadata on clips.
metadata.get(clip_id)
Returns all metadata key-value pairs for a clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Clip ID |
Returns: Table of key-value string pairs, or nil, error_message
Example:
local meta = metadata.get(123)
if meta then
for key, value in pairs(meta) do
log(key .. " = " .. value)
end
end
metadata.set(clip_id, key, value)
Sets a single metadata key-value pair on a clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Clip ID |
| key | string | Yes | Metadata key (max 256 characters) |
| value | string | Yes | Metadata value (max 4096 characters) |
Returns: true on success, or false, error_message
Limits: Max 50 key-value pairs per clip.
Example:
metadata.set(123, "source", "screenshot")
metadata.set(123, "project", "docs")
metadata.delete(clip_id, key)
Removes a single metadata key from a clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Clip ID |
| key | string | Yes | Metadata key to remove |
Returns: true on success, or false, error_message
metadata.set_bulk(clip_id, table)
Atomically replaces all metadata on a clip with the provided table.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Clip ID |
| table | table | Yes | Key-value pairs to set (replaces all existing metadata) |
Returns: true on success, or false, error_message
Example:
metadata.set_bulk(123, {
source = "camera",
project = "photos",
rating = "5",
})
image
Go-side image processing functions. These operate on clip data directly by clip ID, so you don't need to decode image bytes in Lua.
image.info(clip_id)
Returns dimensions and format of an image clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Clip ID |
Returns: Table with width, height, format, size, and has_exif fields, or nil, error_message
image.resize(clip_id, width, height, opts?)
Resizes an image clip and returns the result as raw data.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Source clip ID |
| width | number | Yes | Target width (must be positive). Max 10000. |
| height | number | Yes | Target height (must be positive). Max 10000. |
| opts | table | No | Options |
| opts.fit | string | No | Fit mode: "fill" (default), "contain", or "cover" |
Returns: Table with data (base64-encoded image) and mime_type, or nil, error_message
image.overlay_text(clip_id, opts)
Draws text onto an image clip. Uses the embedded IBM Plex Mono font.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Source clip ID |
| opts | table | Yes | Text overlay options |
| opts.text | string | Yes | Text to draw |
| opts.position | string | No | Named position: "center", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right" |
| opts.x | number | No | X position (overrides position) |
| opts.y | number | No | Y position (overrides position) |
| opts.size | number | No | Font size |
| opts.color | string | No | Hex color (e.g., "#FF0000") |
| opts.opacity | number | No | Text opacity (0.0 to 1.0) |
Returns: Table with data (base64-encoded image) and mime_type, or nil, error_message
image.composite(opts)
Creates a canvas and composites multiple image layers onto it. Up to 50 layers.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| opts | table | Yes | Composite options |
| opts.width | number | Yes | Canvas width |
| opts.height | number | Yes | Canvas height |
| opts.layers | table | Yes | Array of layer objects (max 50) |
Layer object:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Image clip ID |
| x | number | No | X offset on canvas |
| y | number | No | Y offset on canvas |
| width | number | No | Resize layer width |
| height | number | No | Resize layer height |
Returns: Table with data (base64-encoded image) and mime_type, or nil, error_message
image.convert(clip_id, format, opts?)
Converts an image clip to a different format.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Source clip ID |
| format | string | Yes | Target format: "png", "jpeg", or "jpg" |
| opts | table | No | Options |
| opts.quality | number | No | JPEG quality (1-100, default: 85). Only applies to JPEG output. |
Returns: Table with data (base64-encoded image) and mime_type, or nil, error_message
Example:
-- Convert PNG to JPEG at 85% quality
local result = image.convert(123, "jpeg", { quality = 85 })
if result then
clips.create({
data = result.data,
data_encoding = "base64",
content_type = result.mime_type,
filename = "converted.jpg",
})
end
image.dominant_colors(clip_id, count?)
Extracts dominant colors from an image using k-means clustering.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Clip ID |
| count | number | No | Number of colors to return (default: 5, max: 20) |
Returns: Array of hex color strings, or nil, error_message
image.grayscale_pixels(clip_id, width, height)
Returns a flat array of grayscale luminance values (0-255). Useful for ASCII art, perceptual hashing, or image analysis.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Clip ID |
| width | number | Yes | Target sample width |
| height | number | Yes | Target sample height |
Returns: Flat array of luminance values (integers 0-255, length = width * height, row-major order), or nil, error_message
Limit: Max 1 million pixels (width * height).
image.metadata(clip_id)
Returns EXIF metadata from an image clip.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id | number | Yes | Clip ID |
Returns: Table with fields like camera_make, camera_model, lens, iso, aperture, shutter_speed, focal_length, date, and gps (a nested table with latitude and longitude). Missing fields are nil. Returns an empty table for images without EXIF data (e.g., PNGs). Returns nil, error_message on failure.
image.diff(clip_id1, clip_id2)
Compares two images and returns a similarity score plus a visual diff image.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| clip_id1 | number | Yes | First image clip ID |
| clip_id2 | number | Yes | Second image clip ID |
Returns: Table with similarity (0.0 to 1.0, where 1.0 is identical), diff_data (base64-encoded PNG of the visual diff), and diff_mime_type, or nil, error_message
Image Safety Limits
All image operations enforce these limits:
- Decompression bomb guard: max 100 megapixels per image
- Output size guard: max 50MB base64-encoded PNG output
modal
Display result modals to the user from plugin actions.
modal.show(opts)
Opens a modal dialog showing plugin output. Supports markdown, plain text, and image content.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| opts | table | Yes | Modal options |
| opts.title | string | Yes | Modal title (max 200 characters) |
| opts.content | string | Yes | Content to display (max 1MB) |
| opts.format | string | Yes | "markdown", "text", or "image" |
| opts.copy_data | string | No | Data placed on clipboard when user clicks Copy (max 1MB) |
| opts.paste_data | string | No | Data to create a new clip when user clicks Paste (max 10MB) |
| opts.paste_data_base64 | boolean | No | If true, paste_data is base64-encoded binary |
| opts.paste_name | string | No | Filename for the pasted clip |
| opts.paste_content_type | string | No | MIME type for the pasted clip |
Returns: true on success, or false, error_message
Only one modal can be open at a time across all plugins. If another modal is already showing, modal.show returns false. Modals from async actions are queued and shown when the guard is released.
Example:
-- Show markdown result
modal.show({
title = "Analysis Results",
content = "## Summary\n\nFound **3** duplicate images.",
format = "markdown",
copy_data = "3 duplicates found"
})
-- Show a generated image
modal.show({
title = "Generated Image",
content = base64_png_data,
format = "image",
paste_data = base64_png_data,
paste_data_base64 = true,
paste_name = "generated.png",
paste_content_type = "image/png"
})
Resource Limits
Plugins operate within strict resource limits to ensure system stability:
| Resource | Limit |
|---|---|
| Execution time | 30 seconds per handler, 5 minutes for async UI actions |
| Memory | 50 MB per plugin |
| HTTP requests | 100 per minute |
| File operations | 50 per minute |
| Storage | 10 MB per plugin (not currently enforced) |
| Toast notifications | 5 per minute |
| Clip data size | 50 MB maximum |
| File read size | 50 MB maximum |
| HTTP response size | 50 MB maximum |
| HTTP request timeout | 5 minutes |
| Modal title | 200 characters |
| Modal content | 1 MB |
| Modal paste_data | 10 MB |
| Toast message | 200 characters |
| Tag name | 50 characters |
Behavior when limits are exceeded:
- Execution time: Handler is terminated with a timeout error
- Rate limits: Operation returns an error message
- Size limits: Operation is rejected with an error message
- Toast rate limit: Notification is silently dropped (returns false)
Error Handling
Most API functions return errors as a second value:
local result, err = some_api_function()
if result == nil and err then
log("Error: " .. err)
return
end
Common patterns:
-- Check for nil result
local clip = clips.get(id)
if not clip then
log("Clip not found")
return
end
-- Check boolean success with error
local success, err = clips.delete(id)
if not success then
log("Delete failed: " .. (err or "unknown error"))
end
-- Handle HTTP errors
local resp, err = http.get(url)
if not resp then
log("Request failed: " .. err)
return
end
if resp.status ~= 200 then
log("HTTP error: " .. resp.status)
return
end
Related
- Plugin Manifest -- declare permissions and UI actions
- Event Handling -- subscribe to app events