Repository files navigation

A straightforward solution for using the AT Protocol and Bluesky, written in Swift.

ATProtoKit is an easy-to-understand API library that leverages the AT Protocol with the type-safety and ease-of-use you’ve come to expect with the Swift programming language. Whether you’re building a bot, a server app, or just another user-facing Bluesky client, this project should hopefully get you up to speed.

This Swift package mainly focuses on the client side of the AT Protocol. This is essentially a combination of theapi andxrpc packages from the officialatproto TypeScript repository.

letconfig=ATProtocolConfiguration()Task{print("Starting application...")do{tryawait config.authenticate(with:"lucy.bsky.social", password:"hunter2")letatProtoKit=awaitATProtoKit(sessionConfiguration: config)letatProtoBluesky=ATProtoBluesky(atProtoKitInstance: atProtoKit)letpostResult=tryawait atProtoBluesky.createPostRecord(text:"Hello Bluesky!")print(postResult)}catch{print("Error:\(error)")}}

I believe Bluesky and its accompanying AT Protocol gives the perfect balance between embracing decentralization and simplifying the user experience. Because of this, I wanted a way for Swift developers to use the AT Protocol in a way that feels right at home, both client-side with Apple's platforms, and server-side with Linux. For this reason, I decided to open source this project.

• Full compatibility with Apple’s APIs for each of the platforms.
• Written with adherence to the Swift API Design Guidelines.
• Well-written documentation for all of the AT Protocol and Bluesky APIs.
• A RichText helper to parse text into the applicable facets.
• Easily validate different identifiers.
• A powerful Firehose API that retrieves and filters events and records in real-time.
• A logging tool for easy debugging.

You can use the Swift Package Manager to download and import the library into your project:

dependencies:[.package(url:"https://github.com/MasterJ93/ATProtoKit.git", from:"0.32.0")]

Then undertargets:

targets:[.target(        // name: "[name of target]",        dependencies:[.product(name:"ATProtoKit",package:"atprotokit")])]

The Projects page isn't completed, but you can still view it through itsProjects page.

As shown in the Example Usage, it all starts withATProtocolConfiguration:

import ATProtoKitletconfig=ATProtocolConfiguration()

By default,ATProtocolConfiguration conforms tohttps://bsky.social. However, if you’re using a different distributed service, you can specify the URL:

letresult=ATProtocolConfiguration(pdsURL:"https://example.social")

After that, use theauthenticate() method, and pass in the handle and password of the user account. Once you've passed in theATProtocolConfiguration object to theATProtoKitclass, use thegetUserSession() method, as well as theATProtocolConfiguration.sessionConfiguration.keychainProtocol property. These two contains all of the elements you need, such as the session tokens, decentralized identifier (DID), and service endpoint:

Task{do{tryawait config.authenticate(with:"lucy.bsky.social", appPassword:"hunter2")        // The session object is contains in the `ATProtoKit` object:letatProtoKit=ATProtoKit(sessionConfiguration: config)        iflet keychain=tryawait atProtoKit.keychainProtocol(){print("Result (Access Token):\(keychain.retrieveAccessToken())")print("Result (Refresh Token):\(keychain.retrieveRefreshToken())")}                if let session=tryawait atProtoKit.getUserSession(){print("Result (Service Endpoint):\(session.serviceEndpoint)")print("Result (DID):\(session.sessionDID)")}}catch{print("Error:\(error)")}}

To use ATProtoKit in your apps, your app should target the specific version numbers:

• iOS andiPadOS 14 or later.
• macOS 13 or later.
• tvOS 14 or later.
• visionOS 1 or later.
• watchOS 9 or later.

For Linux, you need to use Swift 6.0 or later. On Linux, the minimum requirements include:

• Amazon Linux 2
• Debian 12
• Fedora 39
• Red Hat UBI 9
• Ubuntu 20.04

For Windows, you'll need Swift 6.1 or later. On Windows, the minimum requirements include:

• Windows 10 or later
• Windows Server 2022 or later.

For Android, you'll need Swift 6.1 or later. On Android, the minimum requirements include:

• Android 10 or later.
• Android SDK version 29 or later.

At the moment, Android is in its experimental phase. Plans to take it out of this phase will require testing all parts of the package.

You can also use this project for any programs you make using Swift and running onDocker.

While this project will change significantly, feedback, issues, and contributions are highly welcomed and encouraged. If you'd like to contribute to this project, please be sure to read both theAPI Guidelines as well as theContributor Guidelines before submitting a pull request. Any issues (such as bug reports or feedback) can be submitted in theIssues tab. Finally, if there are any security vulnerabilities, please readSECURITY.md for how to report it.

If you have any questions, you can ask me on Bluesky (@cjrriley.ca). And while you're at it, give me a follow! I'm also active on theATProto Touchers Discord server.

This Swift package is using the MIT License. Please viewLICENSE.md for more details.

ATProtoKit contains a number of third-party Swift packages in order to run effectively. Please seeNOTICE.txt for more information.