@atproto/api session refactor: BskyAgent deprecated, some session hooks removed

What this means for you

Many Bluesky apps are built with a free code toolkit that Bluesky publishes. In August 2024 Bluesky changed how that toolkit keeps you logged in, to get ready for a safer login method. If you only use apps, you notice nothing. App makers who update the toolkit may have to change some code, or logins in their app can break.

The details

• Why: make @atproto/api compatible with OAuth session management. The post says you "can keep using the current app password authentication system" until OAuth launches; see AT Protocol publishes its OAuth specification.
• New class layout: XrpcClient is the base, AtpBaseClient extends it, the abstract Agent extends that, AtpAgent adds password sessions, and BskyAgent extends AtpAgent with nothing new. Use Agent as the type you accept and AtpAgent only to create one.
• Breaking: setting the fetch property after creation now throws (it is read only as fetchHandler); fetch(), Request and Headers must be global, so add a polyfill if needed; AtpBaseClient was removed and AtpServiceClient renamed to AtpBaseClient; setSessionPersistHandler is gone, use the persistSession constructor option.
• Deprecated: the default exports of @atproto/api and @atproto/xrpc, the Client and ServiceClient classes (use XrpcClient), BskyAgent (use AtpAgent), and the xrpc and api properties (use the instance itself).
• Client-side rate limiting: instead of patching agent.api.xrpc.call, wrap the fetch you pass to the AtpAgent constructor.
• Fix: a bug that could make session data invalid when cloning agents, for example with agent.withProxy().
• Source note: the post was on docs.bsky.app, which now redirects to bsky.network and no longer serves it. The text is in Bluesky's own bluesky-social/bsky-docs repository.

What to do next

• Business owners: Nothing.
• Marketers and agencies: Nothing, unless your Bluesky tool logs you out after an update; tell the vendor.
• Developers: Move to Agent and AtpAgent, set persistSession and fetch in the constructor, drop default imports, and test session refresh after upgrading.