Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/masterj93/atprotokit
A straightforward solution for using AT Protocol and Bluesky, written in Swift.
https://github.com/masterj93/atprotokit
api atproto atprotocol bluesky decentralized lexicon social-media swift swift-package-manager xrpc
Last synced: 3 days ago
JSON representation
A straightforward solution for using AT Protocol and Bluesky, written in Swift.
- Host: GitHub
- URL: https://github.com/masterj93/atprotokit
- Owner: MasterJ93
- License: mit
- Created: 2024-02-15T17:50:18.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-12-12T01:28:06.000Z (10 days ago)
- Last Synced: 2024-12-13T23:55:45.406Z (8 days ago)
- Topics: api, atproto, atprotocol, bluesky, decentralized, lexicon, social-media, swift, swift-package-manager, xrpc
- Language: Swift
- Homepage: https://atprotokit.cjrriley.com/documentation/atprotokit/
- Size: 145 MB
- Stars: 95
- Watchers: 2
- Forks: 17
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
ATProtoKit
A straightforward solution for using the AT Protocol and Bluesky, written in Swift.
[](https://swiftpackageindex.com/MasterJ93/ATProtoKit)
[](https://swiftpackageindex.com/MasterJ93/ATProtoKit)
[](https://github.com/MasterJ93/ATProtoKit)
[](https://github.com/MasterJ93/ATProtoKit)
[](https://bsky.app/profile/cjrriley.com)
---
> [!CAUTION]
> ***This API library is highly unstable. Things will change. Things are incomplete. Things will break. Until the project reaches version 1.0.0, stability will not be guaranteed.***
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.
## Example Usage
```swift
let config = ATProtocolConfiguration(handle: "lucy.bsky.social", appPassword: "hunter2")
Task {
print("Starting application...")
do {
try await config.authenticate()
let atProto = ATProtoKit(sessionConfiguration: config)
let atProtoBluesky = ATProtoBluesky(atProtoKitInstance: atProto)
let postResult = try await atProtoBluesky.createPostRecord(text: "Hello Bluesky!")
print(postResult)
} catch {
print("Error: \(error)")
}
}
```
## Motivation
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.
## Features
- [x] Full compatibility with Apple’s APIs for each of the platforms.
- [x] Written with adherence to the Swift API Design Guidelines.
- [ ] Well-written documentation for all of the AT Protocol and Bluesky APIs.
- [x] A RichText helper to parse text into the applicable facets.
- [ ] Easily identify and validate different identifiers.
- [ ] A powerful Firehose API that retrieves and filters events and records in real-time.
- [x] A logging tool for easy debugging.
> [!NOTE]
> Not all features above have been implemented; however, they will be, soon.
## Installation
You can use the Swift Package Manager to download and import the library into your project:
```swift
dependencies: [
.package(url: "https://github.com/MasterJ93/ATProtoKit.git", from: "0.21.0")
]
```
Then under `targets`:
```swift
targets: [
.target(
// name: ...,
dependencies: [
.product(name: "ATProtoKit", package: "atprotokit")
]
)
]
```
## Roadmap
The Projects page isn't completed, but you can still view it through its [Projects](https://github.com/users/MasterJ93/projects/2) page.
## Quick Start
As shown in the Example Usage, it all starts with `ATProtocolConfiguration`, which uses the handle, app password, and pdsURL to access and create a session:
```swift
import ATProtoKit
let config = ATProtocolConfiguration(handle: "lucy.bsky.social", appPassword: "hunter2")
```
By default, `ATProtocolConfiguration` conforms to `https://bsky.social`. However, if you’re using a different distributed service, you can specify the URL:
```swift
let result = ATProtocolConfiguration(handle: "lucy.example.social", appPassword: "hunter2", pdsURL: "https://example.social")
```
This session contains all of the elements you need, such as the access and refresh tokens:
```swift
Task {
do {
// The session object is contained in the `ATProtocolConfiguration` object:
try await config.authenticate()
print("Result (Access Token): \(config.session?.accessToken)")
print("Result (Refresh Token): \(config.session?.refreshToken)")
} catch {
print("Error: \(error)")
}
}
```
## Requirements
To use ATProtoKit in your apps, your app should target the specific version numbers:
- **iOS** and **iPadOS** 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. At this time, you must use `@preconcurrency` when importing ATProtoKit. On Linux, the minimum requirements include:
- **Ubuntu** 18.04
- **CentOS** 7
- **Red Hat UBI** 9
- **Debian** 12
- **Fedora** 39
You can also use this project for any programs you make using Swift and running on **Docker**.
> [!WARNING]
> As of right now, Windows support is theoretically possible, but not has not been tested to work. For other platforms (such as Android), this is also not tested, but should be theoretically possible. While it’s not a goal to make it fully compatible, contributions and feedback on the matter are welcomed.
## Submitting Contributions and Feedback
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 the [API Guidelines](https://github.com/MasterJ93/ATProtoKit/blob/main/API_GUIDELINES.md) as well as the [Contributor Guidelines](https://github.com/MasterJ93/ATProtoKit/blob/main/CONTRIBUTING.md) before submitting a pull request. Any issues (such as bug reports or feedback) can be submitted in the [Issues](https://github.com/MasterJ93/ATProtoKit/issues) tab. Finally, if there are any security vulnerabilities, please read [SECURITY.md](https://github.com/MasterJ93/ATProtoKit/blob/main/SECURITY.md) for how to report it.
If you have any questions, you can ask me on Bluesky ([@cjrriley.com](https://bsky.app/profile/cjrriley.com)). And while you're at it, give me a follow! I'm also active on the [Bluesky API Touchers](https://discord.gg/3srmDsHSZJ) Discord server.
## License
This Swift package is using the MIT License. Please view [LICENSE.md](https://github.com/MasterJ93/ATProtoKit/blob/main/LICENSE.md) for more details.
The documentation text used by Bluesky is licenced under the MIT Licence. Please view [ATPROTO-LICENSE.md](ATProtoLicense/ATPROTO-LICENSE.txt) for more details.