Bluesky Social Plugin

Bluesky event plugin for the xyOps Workflow Automation System. This plugin is a pure Node.js implementation and talks directly to the Bluesky XRPC endpoints.

Quick Start

Get your Bluesky app password at: https://bsky.app/settings/app-passwords

You will need the following environment variables (recommend storing them in a secret vault):

Environment Variable	Description
BLUESKY_IDENTIFIER	Your Bluesky identifier, e.g. your-handle.bsky.social.
BLUESKY_APP_PASSWORD	Your Bluesky App Password, which you can obtain here.
BLUESKY_SERVICE_URL	Optional service URL (defaults to https://bsky.social).

Requirements

• npx
• git

What this plugin does

• Authenticates to Bluesky.
• Reads posts, profiles, followers, and timelines.
• Sends posts, images, and videos.
• Likes, reposts, follows, and mutes users.
• Returns the Bluesky API response as job output data.

File Inputs

For send_image, send_images, and send_video, pass files into the xyOps job.

Tools

All tools are selected via the Toolset parameter in xyops.json. When a tool is selected, its fields are flattened into params at the top level.

Notes on common fields:

• cursor is an opaque pagination token returned by Bluesky. Treat it as a string and pass it back verbatim to fetch the next page. Leave it empty for the first page.
• limit is the maximum number of items to return. Where applicable, Bluesky accepts 1-100. If you leave it empty or 0, the server default is used (often 50).

Check Auth Status

Check if the current session is authenticated. No parameters are used.

Get Profile

Get a user profile. If you omit the handle, the authenticated user is used.

Parameter	Type	Required	Description	Default
handle	text	No	Handle or DID to fetch (e.g. user.bsky.social or did:plc:...).	Current user

Get Follows

Get users followed by an account.

Parameter	Type	Required	Description	Default
handle	text	No	Handle or DID to fetch follows for.	Current user
limit	number	No	Max results to return (1-100).	50
cursor	text	No	Pagination cursor returned from a previous call.	-

Get Followers

Get users who follow an account.

Parameter	Type	Required	Description	Default
handle	text	No	Handle or DID to fetch followers for.	Current user
limit	number	No	Max results to return (1-100).	50
cursor	text	No	Pagination cursor returned from a previous call.	-

Like Post

Like a post. Requires the target post URI and CID (both are returned by Bluesky APIs).

Parameter	Type	Required	Description	Default
uri	text	Yes	Post URI to like (e.g. at://did:.../app.bsky.feed.post/...).	-
cid	text	Yes	Post CID to like.	-

Unlike Post

Unlike a previously liked post. Use the like_uri from the like_post response.

Parameter	Type	Required	Description	Default
like_uri	text	Yes	Like record URI to delete.	-

Send Post

Send a text post. Optional fields allow replies, embeds, languages, and facets.

Parameter	Type	Required	Description	Default
text	textarea	Yes	Text content of the post.	-
profile_identify	text	No	Handle or DID to post as. If omitted, uses the authenticated user.	Current user
reply_to	json	No	Reply reference with root and parent objects containing uri and cid.	-
embed	json	No	Raw Bluesky embed object (external link, record, or media).	-
langs	json	No	List of BCP-47 language codes (e.g. ["en"]).	["en"]
facets	json	No	Rich-text facets (mentions, links, hashtags).	-

Repost

Repost another user's post.

Parameter	Type	Required	Description	Default
uri	text	Yes	Post URI to repost.	-
cid	text	Yes	Post CID to repost.	-

Unrepost

Remove a repost you previously created. Use the repost_uri from the repost response.

Parameter	Type	Required	Description	Default
repost_uri	text	Yes	Repost record URI to delete.	-

Get Likes

Get likes for a post.

Parameter	Type	Required	Description	Default
uri	text	Yes	Post URI to query.	-
cid	text	No	Optional CID for the post.	-
limit	number	No	Max results to return (1-100).	50
cursor	text	No	Pagination cursor returned from a previous call.	-

Get Reposted By

Get users who reposted a post.

Parameter	Type	Required	Description	Default
uri	text	Yes	Post URI to query.	-
cid	text	No	Optional CID for the post.	-
limit	number	No	Max results to return (1-100).	50
cursor	text	No	Pagination cursor returned from a previous call.	-

Get Post

Get a specific post by record key and author.

Parameter	Type	Required	Description	Default
post_rkey	text	Yes	Record key of the post (last segment of the at:// URI).	-
profile_identify	text	No	Handle or DID of the post author.	Current user
cid	text	No	Optional CID of the post.	-

Get Posts

Get multiple posts by their URIs.

Parameter	Type	Required	Description	Default
uris	json	Yes	Array of post URIs to retrieve.	-

Get Timeline

Get posts from your home timeline.

Parameter	Type	Required	Description	Default
algorithm	text	No	Optional timeline algorithm ID. Leave empty for the default timeline.	Default algorithm
cursor	text	No	Pagination cursor returned from a previous call (opaque string).	-
limit	number	No	Max results to return (1-100).	Server default

Get Author Feed

Get posts from a specific user (or the authenticated user if omitted).

Parameter	Type	Required	Description	Default
actor	text	No	Handle or DID of the user.	Current user
cursor	text	No	Pagination cursor returned from a previous call.	-
filter	text	No	Optional filter for post types (per Bluesky API).	-
limit	number	No	Max results to return (1-100).	Server default
include_pins	checkbox	No	Include pinned posts when available.	false

Get Post Thread

Get a full conversation thread for a post.

Parameter	Type	Required	Description	Default
uri	text	Yes	Post URI to fetch the thread for.	-
depth	number	No	How many reply levels to include. Use 0 or empty for server default.	Server default
parent_height	number	No	How many parent posts to include. Use 0 or empty for server default.	Server default

Resolve Handle

Resolve a handle to a DID.

Parameter	Type	Required	Description	Default
handle	text	Yes	Handle to resolve (e.g. user.bsky.social).	-

Mute User

Mute a user by handle or DID.

Parameter	Type	Required	Description	Default
actor	text	Yes	Handle or DID of the user to mute.	-

Unmute User

Unmute a previously muted user.

Parameter	Type	Required	Description	Default
actor	text	Yes	Handle or DID of the user to unmute.	-

Unfollow User

Unfollow a user. Use the follow_uri from follow_user.

Parameter	Type	Required	Description	Default
follow_uri	text	Yes	Follow record URI to delete.	-

Send Image

Send a post with a single image. The image file is taken from the job input (first file in input.files).

Parameter	Type	Required	Description	Default
text	text	Yes	Text content of the post.	-
image_alt	text	Yes	Alt text description for the image.	-
profile_identify	text	No	Handle or DID to post as.	Current user
reply_to	json	No	Reply reference with root and parent objects containing uri and cid.	-
langs	json	No	List of BCP-47 language codes.	["en"]
facets	json	No	Rich-text facets (mentions, links, hashtags).	-

Send Images

Send a post with multiple images (up to 4). Images are taken from the job input files in order.

Parameter	Type	Required	Description	Default
text	text	Yes	Text content of the post.	-
image_alts	json	No	Array of alt-text strings, one per image.	Empty strings
profile_identify	text	No	Handle or DID to post as.	Current user
reply_to	json	No	Reply reference with root and parent objects containing uri and cid.	-
langs	json	No	List of BCP-47 language codes.	["en"]
facets	json	No	Rich-text facets (mentions, links, hashtags).	-

Send Video

Send a post with a video. The video file is taken from the job input (first file in input.files).

Parameter	Type	Required	Description	Default
text	text	Yes	Text content of the post.	-
video_alt	text	No	Alt text description for the video.	-
profile_identify	text	No	Handle or DID to post as.	Current user
reply_to	json	No	Reply reference with root and parent objects containing uri and cid.	-
langs	json	No	List of BCP-47 language codes.	["en"]
facets	json	No	Rich-text facets (mentions, links, hashtags).	-

Delete Post

Delete a post created by the authenticated user.

Parameter	Type	Required	Description	Default
uri	text	Yes	Post URI to delete.	-

Follow User

Follow a user by handle. The handle is resolved to a DID automatically.

Parameter	Type	Required	Description	Default
handle	text	Yes	Handle to follow (e.g. user.bsky.social).	-

Testing

When invoked by xyOps the script expects JSON input via STDIN. You can also test locally by piping a JSON file into the command.

Example input JSON:

{
	"params": {
		"tool": "get_timeline",
		"limit": 1
	}
}

Example command:

export BLUESKY_IDENTIFIER="your-handle.bsky.social"
export BLUESKY_APP_PASSWORD="your-app-password"

cat MYFILE.json | node index.js

Data Collection

This plugin does not collect or transmit any metrics or user data beyond the Bluesky API calls you request.

License

MIT