Introduction

The BunBase iOS SDK is a Swift Package with no third-party dependencies. It targets iOS 16+, macOS 13+, watchOS 9+, and tvOS 16+.

Installation

Swift Package Manager (Xcode)

1. File → Add Package Dependencies…
2. Enter the repository URL and select version 0.13.0 or later.
3. Add BunBase to your app target.

Package.swift

dependencies: [
    .package(url: "https://github.com/your-org/bunbase-swift", from: "0.13.0"),
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "BunBase", package: "bunbase-swift"),
    ]),
]

Setup

import BunBase

let client = BunBaseClient(url: "https://your-bunbase-server.com")

The client is a singleton. Create one instance per app.

// App.swift or a shared file
import BunBase

extension BunBaseClient {
    static let shared = BunBaseClient(url: "https://your-bunbase-server.com")
}

API key (server-to-server)

let client = BunBaseClient(url: "https://api.example.com", apiKey: "bb_...")

When apiKey is set, every request sends X-API-Key instead of Bearer tokens and the refresh flow is skipped.

Token persistence

Tokens are persisted to the Keychain automatically on login and restored on the next app launch — no extra setup needed.

Automatic token refresh

The SDK intercepts 401 responses and automatically calls /auth/refresh before retrying. Multiple concurrent 401s share a single refresh call.

If refresh fails, tokens are cleared, auth.currentUserPublisher emits nil, and the original call throws BunBaseError.unauthenticated.

Auth state

Auth state is exposed as a Combine AnyPublisher<AuthUser?, Never>:

import Combine

// SwiftUI (via @StateObject ViewModel)
client.auth.currentUserPublisher
    .receive(on: RunLoop.main)
    .assign(to: &$user)

// UIKit
client.auth.currentUserPublisher
    .receive(on: RunLoop.main)
    .sink { [weak self] user in self?.updateUI(user) }
    .store(in: &cancellables)