@kody/bluesky

@kody/bluesky

Official Bluesky butterfly from Bluesky brand assets (bluesky_media_kit_logo_transparent_1.svg). Paths are unmodified. Bluesky® and the butterfly mark are trademarks of Bluesky Social PBC.

Intent

Give agents fork-ready Bluesky and AT Protocol helpers for profiles, posts, search, notifications, and guarded social writes. Posts should behave like posts created in the Bluesky UI, including clickable links and external cards with uploaded thumbnails.

This listing is meant to be forked. The live @kody/bluesky package does not share a handle. After you fork, store your handle in packageStorage and save your app password.

What it does

• Verify Bluesky auth and read a profile, feed, thread, or notifications
• Resolve handles and search posts
• Call uncommon AT Protocol XRPC methods through one helper
• Draft or publish posts, likes, reposts, follows only after confirm: true
• Publish links with UTF-8 byte-indexed facets and optional external cards

Prerequisites / setup

Auth is a Bluesky handle plus an app password. There is no Kody Bluesky OAuth integration. Never paste the app password into chat. Agents: see AGENTS.md for import paths, smoke, and dryRun.

1. App password secret

1. Create an app password at https://bsky.app/settings/app-passwords. Do not use your account password.
2. Save it as blueskyAppPassword and approve the hosts below. The package declares this as a raw credential slot, because Bluesky's session call takes the app password in the request body, so the approval page will say the package can read the value:

https://kody.codes/account/secrets/new?name=blueskyAppPassword&description=Bluesky%20app%20password%20for%20AT%20Protocol%20session%20creation&allowedHosts=bsky.social,*.bsky.network&scope=user

Unauthenticated AppView reads (get-profile, get-author-feed, get-post-thread, and other GET request calls) default to https://public.api.bsky.app and do not need the secret. Session creation and authenticated calls use https://bsky.social. Pass service to override either.

2. Handle in package storage

After you fork (or when invoking your own copy), persist the default actor in that package's storage (for example blueskyHandle → yourhandle.bsky.social), or pass identifier / actor / handle on each call. Do not treat the live @kody/bluesky storage bucket as yours.

Done when

• blueskyAppPassword is saved with the hosts above, and a handle is stored (or passed per call)
• Smoke-test returns { ok: true } (setup-only when credentials are missing; live profile read when present)
• Mutating helpers refuse without confirm: true; dryRun: true never creates a session

Branding

This package is not affiliated with or endorsed by Bluesky Social PBC. Keep LICENSE (MIT), ## Intent, and community-icon.svg intact for community listing.

Docs

• AT Protocol
• App passwords
• HTTP API (XRPC)