# @kody/bluesky

Official Bluesky butterfly from [Bluesky brand assets](https://bsky.social/about/support/icons) (`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`](./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:

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

| Host | When to approve |
| --- | --- |
| `bsky.social` | Session create and authenticated XRPC (default auth service) |
| `*.bsky.network` | Account PDS hosts after session (for example `*.host.bsky.network`) |

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](https://atproto.com/docs)
- [App passwords](https://bsky.app/settings/app-passwords)
- [HTTP API (XRPC)](https://docs.bsky.app/docs/advanced-guides/api-directory)