Cross-platform Swift library for the Mastodon API

TootSDK is a framework for Mastodon and the Fediverse, for iOS. It provides a toolkit for authorizing a user with an instance, and interacting with their posts.

TootSDK is a community developed SDK for Mastodon and the Fediverse. It is designed to work with all major servers (Mastodon, Pleroma, PixelFed etc).

You can use TootSDK to build a client for Apple operating systems, or Linux with Vapor.

When app developers build apps for Mastodon and the Fediverse, every developer ends up having to solve the same set of problems when it comes to the API and data model.

Konstantin and Dave decided to share this effort.

TootSDK is a shared Swift Package that any client app can be built on.

• Async/Await based. All asynchronous functions are defined as Async ones that you can use with Async/Await code
• Internal consistency and standardization of model property names
• Standardization across all supported Fediverse APIs
• Platform agnostic (TootSDK shouldn't care if it's on iOS, macOS or Linux!)

Please don't hesitate to open an issue or create a PR for features you need 🙏

It's easy to get started with TootSDK.

• Add TootSDK to your project via Swift Package Manager: https://github.com/TootSDK/TootSDK

• Instantiate with an instanceURL and accessToken:

  let instanceURL = URL(string: "social.yourinstance.com")
  let client = try await TootClient(connect: instanceURL, accessToken: "USERACCESSTOKEN")

<key>com.apple.security.network.client</key>
<true/>

• Instantiate your client without a token:

let client = try await TootClient(connect: url)

• Use the sign in helper we've created based on ASWebAuthenticationSession:

let client = try await TootClient(connect: url)

guard let accessToken = try await client.presentSignIn(callbackURI: callbackURI) else {
    // handle failed sign in
    return
}

That's it 🎉!

We recommend keeping the accessToken somewhere secure, for example the Keychain.

• Instantiate your client without a token:

let client = try await TootClient(connect: instanceURL)

• Retrieve an authorization URL to present to the user (so they can sign in)

let authURL = client.createAuthorizeURL(callbackURI: "myapp://someurl")

• Present the the authorization URL as a web page
• Let the user sign in, and wait for the callbackURI to be called
• When that callbackURI is called, give it back to the client to collect the token

let accessToken = client.collectToken(returnUrl: url, callbackURI: callbackURI)

We recommend keeping the accessToken somewhere secure, for example the Keychain.

Once you have your client connected, you're going to want to use it. Our example apps and reference docs will help you get into the nitty gritty of it all, but some key concepts are highlighted here.

let items = try await client.getTimeline(.home)
let posts = items.result

let items = try await client.getTimeline(.home, PagedInfo(minId: 100))
let posts = items.result

var pagedInfo: PagedInfo?
var posts: [Post] = []

func retrievePosts() async {
    let items = try await client.getTimeline(.home, pagedInfo)
    posts.append(contentsOf: items.result)
    self.pagedInfo = items.pagedInfo
}

var pagedInfo: PagedInfo? = nil
var hasMore = true
let query = TootNotificationParams(types: [.mention])

while hasMore {
  let page = try await client.getNotifications(params: query, pagedInfo)
  for notification in page.result {
    print(notification.id)
  }
  hasMore = page.hasPrevious
  pagedInfo = page.previousPage
}

// open a socket to a specific timeline
let stream = try! await client.streaming.subscribe(to: .userNotification)

do {
    // listen for events
    for try await event in stream {
        print("got event")
        switch event {
        case .connectionUp:
            //...
        case .connectionDown:
            //...
        case .receivedEvent(let eventContent):
            //...
        }
    }
} catch {
    print(String(describing: error))
}

let instance = try await client.getInstanceInfo()
if instance.registrations == false {
  // instance not open for registration
  return
}
// ...

let params = RegisterAccountParams(
      username: name, email: email, password: password, agreement: true, locale: "en")
let token = try await client.registerAccount(params: params)

• Reference documentation is available here
• Examples:
  • swiftyadmin - a command line utility to interact with and control a server using TootSDK
  • tootsdk-release - Example GitHub action to publish a post when a new release is published.

• Our guide to contributing is available here: CONTRIBUTING.md.
• All contributions, pull requests, and issues are expected to adhere to our community code of conduct: CODE_OF_CONDUCT.md.

TootSDK is licensed with the BSD-3-Clause license, more information here: LICENSE.MD

This is a permissive license which allows for any type of use, provided the copyright notice is included.

• The Mastodon API documentation https://github.com/mastodon/documentation
• We hat-tip top Metatext's source for some guidance on what's where: https://github.com/metabolist/metatext
• Kris Slazinski for our TootSDK logo 🤩

• Fedicat
• Pipilo
• TootyGraph
• Topiary
• TootLater
• Oxpecker

• TootSDK fork by technicat