Plugin ABI Contract
Plugins must export four guest functions. All inputs and outputs are UTF-8 JSON strings.
Required Guest Exports
| Export | Input | Output | Purpose |
|---|---|---|---|
describe |
Empty | PluginSpec JSON |
Returns metadata, capabilities, domain allowlist, and credential fields |
validate_auth |
AuthContext JSON |
AuthResult JSON |
Verifies account credentials against the platform API |
publish |
PublishRequest JSON |
PublishResult JSON |
Publishes a post with optional attachments and reply_to |
delete_post |
DeleteRequest JSON |
DeleteResult JSON |
Deletes a published post by platform identifier |
describe()
Called with empty input when loading or verifying a plugin.
Output (PluginSpec):
{
"id": "bluesky-custom",
"version": "0.1.0",
"display_name": "Bluesky (Custom)",
"brand_colour": "#0285ff",
"icon_svg": "<svg viewBox=\"0 0 24 24\"><path d=\"M12 2L2 19h20L12 2z\"/></svg>",
"max_characters": 300,
"max_attachments": 4,
"supported_media_types": ["image/jpeg", "image/png", "image/webp"],
"supports_alt_text": true,
"supports_threads": true,
"supports_delete": true,
"allowed_domains": ["bsky.social", "*.bsky.network"],
"credential_fields": [
{ "key": "identifier", "label": "Handle or Email", "secret": false, "required": true },
{ "key": "app_password", "label": "App Password", "secret": true, "required": true }
]
}
describe() Field Reference
id: Unique plugin identifier matching your claimed slug.version: Strict SemVerMAJOR.MINOR.PATCHstring (for example,"0.1.0"). Extracted automatically during upload; duplicate published versions are rejected.brand_colour: Seven-character#RRGGBBhex string.
SVG Icon Rules
icon_svg must be valid XML with <svg> as the root element and must not contain:
<script>,<foreignObject>,<image>, or<use>elementson*event handler attributes (such asonloadoronclick)javascript:URIs in any attribute
brand_colour must be a 7-character #RRGGBB hex string.
validate_auth()
Input (AuthContext):
{
"workspace_id": "default"
}
Use sp_credential to read configured credential fields and sp_http to verify them.
Output (AuthResult):
{
"ok": true,
"account_handle": "@example.bsky.social",
"error": null
}
publish()
Input (PublishRequest):
{
"text": "Hello from SocialPoster!",
"reply_to": null,
"attachments": [
{
"id": "att_01",
"mime_type": "image/png",
"byte_length": 184320,
"alt_text": "Screenshot of the composer"
}
]
}
Output (PublishResult):
{
"ok": true,
"post_id": "at://did:plc:.../app.bsky.feed.post/3k...",
"post_url": "https://bsky.app/profile/example/post/3k...",
"error": null
}
delete_post()
Input (DeleteRequest):
{
"post_id": "at://did:plc:.../app.bsky.feed.post/3k..."
}
Output (DeleteResult):
{
"ok": true,
"error": null
}