ATProtoKit

ATProtoKit is a Swift framework for developing client and server-side applications interacting with the AT Protocol and Bluesky.

Key capabilities include:

• Identifier Validation: Support for NSIDs, DIDs, Record Keys, AT-URIs, and more.
• Data Streams: Viewing and interacting with data streams (e.g., Firehose).
• Bluesky Integration: Full support for Bluesky-specific features like posting and chat.
• Lexicon Support: Handling various lexicons including AppBskyLexicon, ChatBskyLexicon, ComAtprotoLexicon, and ToolsOzoneLexicon.
• Authentication: Support for standard password authentication and OAuth.

The com.atproto.repo lexicon provides the core operations for interacting with an AT Protocol repository. You can use these topics to create, retrieve, update, delete, and list records, as well as manage blobs and perform batch writes.

Key operations include:

• Batch Writes: com.atproto.repo.applyWrites for applying multiple changes at once.
• Record Lifecycle: com.atproto.repo.createRecord, com.atproto.repo.putRecord, com.atproto.repo.getRecord, com.atproto.repo.deleteRecord, and com.atproto.repo.listRecords.
• Repository Metadata: com.atproto.repo.describeRepo to inspect repository details.
• Blob Management: com.atproto.repo.uploadBlob and com.atproto.repo.listMissingBlobs.

The tools.ozone.team lexicon provides methods for managing membership within an Ozone team. You can add, delete, list, and update members using the following operations:

• Add a member: Use tools.ozone.team.addMember with an AddMemberRequestBody.
• Delete a member: Use tools.ozone.team.deleteMember with a DeleteMemberRequestBody.
• List members: Use tools.ozone.team.listMembers which returns a ListMembersOutput.
• Update a member: Use tools.ozone.team.updateMember with an UpdateMemberRequestBody and an UpdateMember operation.

The app.bsky.notification lexicon provides the API surface for managing user notifications, preferences, and activity subscriptions within the AT Protocol. Developers can use these methods to:

• Retrieve Notifications: List recent notifications and check unread counts.
• Manage Preferences: Get and update notification preferences (including V2 support).
• Handle Activity Subscriptions: List and create subscriptions to specific user activities.
• Push Notifications: Register and unregister push endpoints.
• Track Read State: Update which notifications have been seen.

The SessionDebuggable protocol allows you to inspect outgoing HTTP requests and incoming responses, including JSON payloads, headers, and URLs. This is useful for debugging mismatches between expected and actual JSON data during network communication.

To use it, implement the protocol and pass your implementation to the APIClientConfiguration when initializing ATProtoKit.

public protocol SessionDebuggable: Sendable {
    // Called before a request is sent.
    func logRequest(_ request: URLRequest, body: Data?)

    // Called after a response is received.
    func logResponse(_ response: URLResponse?, data: Data?, error: Error?)
}

SessionConfiguration is the core request-time contract used by ATProtoKit. It must be a concurrency-safe reference type (e.g., a final class with immutable state or an actor).

Required Properties

• pdsURL: The bootstrap Personal Data Server (PDS) URL.
• configuration: The URLSessionConfiguration used by ATProtoKit.
• instanceUUID: The identifier used with UserSessionRegistry.
• authorization(for:): A method that supplies header-based authorization.

Key Extension Points

• requestExecutor: Defaults to nil.
• requestExecutorOwnsAuthorization: Defaults to false.
• authenticatedRequest(for:authorizationRequirement:): Applies the value from authorization(for:) only to requests marked as requiring a session.
• authorizationContext(): Defaults to deriving context from the UserSession registered under instanceUUID.

All Lexicon models in ATProtoKit follow a strict documentation format to ensure clarity and traceability to the official AT Protocol specifications. When reading model documentation, look for these components:

1. One-line summary: A brief description of the model.
2. Spec Note: A block starting with - Note: According to the AT Protocol specifications: "..." containing the official description.
3. SeeAlso/Link: A link to the official JSON lexicon file on GitHub.
4. Undocumented Note: If a property is not covered by the official spec, a specific - Important: block will explain that the documentation is based on inference or requires clarification from Bluesky.

ATProtoKit provides the XRPC client surface but does not implement the AT Protocol OAuth flow itself. To use OAuth, you must use an external OAuth package to handle identity resolution, discovery, PAR, PKCE, DPoP, token persistence, and refresh rotation. You connect your OAuth package to ATProtoKit using ATOAuthSessionConfiguration.

Important: The OAuth package must perform the actual authenticated requests. Because DPoP proofs are bound to specific HTTP methods and URLs, you cannot simply copy an access token into ATProtoKit. The OAuth package must handle the request execution to ensure DPoP headers and nonces are correctly applied.

The bookmark lexicon defines two primary data structures:

• BookmarkDefinition: The core definition of a bookmark entity.
• BookmarkViewDefinition: The structure used when viewing bookmark data (often used in feed or profile views).