Syndicating to Bluesky

Inspired by Jeremy’s post on how he syndicates to Bluesky, I thought I’d follow suit (many examples are useful when it comes to API integration work). A disclaimer though… I’m dubious of the long term prospects of Bluesky for reasons I won’t go into here. That being said, it’s currently a vibrant place, and syndicating from my site to other places keeps my content[1] in my hands.

My setup is a bit of a Rube Goldberg machine:

• I publish notes (optionally with a photo) and bookmarks using Micropub endpoints.
• The endpoints add the note or bookmark as a JF2 JSON file to the git repository of my personal site on GitHub.
• A GitHub Actions workflow is triggered by the addition of a note or bookmark.
• The workflow calls a Node.js script. It calls the script using my Bluesky handle, which is qubyte.codes for me, and an app password. Do not use your actual password! Bluesky makes it pretty easy to create an app password, and when you have one you can add it as a secret for Actions to use at the ./settings/secrets/actions path of your repo site. I’ve called my secret BLUESKYAPPPASSWORD.

The rest of this post is about the script itself. As a rule of thumb, I keep bits of shell glue in Actions workflows, and store the bulk of any logic in a discrete script. That makes it easy to call the script by hand for testing.

I publish notes (optionally with an image) and bookmarks using Micropub endpoints. The note or bookmark is added as a JF2 JSON file to the git repository of my personal site on GitHub. When such a file is created there, a GitHub Actions workflow is triggered, and this workflow in turn calls a Node.js script.

The script is a vanilla Node.js script. While Bluesky does provide API client libraries, I didn’t find it necessary to use one. I managed to write this without any third party libraries. API work is all achieved with plain old fetch.

There are a couple of local libraries which I’ve extracted into their own modules. The first is blueskyAuth, which looks like this:

const createSessionUrl = 'https://bsky.social/xrpc/com.atproto.server.createSession'; export default async function blueskyAuth(handle, appPassword) { const res = await fetch(createSessionUrl, { headers: { 'content-type': 'application/json' }, method: 'POST', body: JSON.stringify({ identifier: handle, password: appPassword }) }); if (!res.ok) { throw new Error( Bluesky responded with an unexpected status: ${res.status} ${await res.text()} ); } return res.json(); // { accessJwt, refreshJwt, did }
}

Bluesky mostly speaks JSON, which is convenient when working in Node.js. To create a session with Bluesky, you JSON encode an object containing your handle and an app password. If successful, the response contains three things of interest:

• accessJwt: A short-lived token used for API requests.
• refreshJwt: A token which can be exchanged for a new accessJwt and refreshJwt when the accessJwt expires.
• did: An identifier. The initial “d”[2] stands for “distributed”, but I recently discovered that the DID plc method used by Bluesky is not actually distributed at all, thanks to Christine Lemmer-Webber’s excellent article on Bluesky and decentralization. I highly recommend reading it to dispel some myths around how decentralized Bluesky is, by design.

My script uses the accessJwt as a token and the did as an identifier in API requests. Since the session is only needed to post one document (and possibly an image), there’s no need to think about refreshing the token, so I don’t use the refreshJwt.

The rest of the script is about one or two API requests. When an image is to be uploaded, that happens first. There’s not much to say here beyond the size restrictions being quite low, and being constrained to JPEGs and PNGs. I don’t think they’re doing much processing of images, so I recommend removing metadata from image uploads. The response of the image upload contains a blob field, which is used as a reference to the image in the second API request in the form of an embedding.

The final request creates the “record” (the note or bookmark) on Bluesky. There’s a lot to unpack here. The creating a post is full of useful samples to help figure out the anatomy of a record creation body.

One fascinating aspect of Bluesky is how text is composed. Rather than some sort of markup language, it uses a more limited concept called rich text facets. Text is linear, and facets (for example, links) are attached to UTF-8 byte ranges of the text. This is awkward for many languages! For example, JavaScript uses UTF-16 to represent string internally (as was the trend in the mid-’90s), so the range of characters you get with naïve string work in JS will give you incorrect offsets. Thankfully Node.js has the venerable Buffer class, which can be used to represent strings as arrays of UTF-8 bytes. A Buffer.byteLength is all it takes to get the UTF-8 size of a string.

Anyway, I’ve put lots of annotations in the syndication script, so hopefully it serves as a useful example!

1. I dislike the “content” term, but I can’t think of something better which encompasses writing and media.ꜛ
2. Unintentional reference to the racing manga.ꜛ

@adactio inspirational.