Introduction

The BunBase Android SDK is a Kotlin-first library for Android (minSdk 24+). It uses coroutines and Flow for async and reactive state, OkHttp for HTTP and WebSocket, and EncryptedSharedPreferences for secure token persistence.

Installation

Add to your module build.gradle.kts:

dependencies {
    implementation("com.bunbase:sdk-android:0.13.0")
}

Make sure mavenCentral() is in your repository list.

Setup

import com.bunbase.sdk.BunBaseClient

// Application or ViewModel:
val client = BunBaseClient(
    context = applicationContext,
    url = "https://your-bunbase-server.com",
)

Tokens are persisted automatically in EncryptedSharedPreferences and restored on the next launch — no extra setup needed.

Without a Context (tests / server-to-server)

val client = BunBaseClient(url = "https://your-bunbase-server.com", apiKey = "bb_...")

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

Automatic token refresh

The SDK intercepts 401 responses and automatically calls /auth/refresh before retrying the original request. Multiple concurrent 401s share a single refresh — no duplicate requests.

If refresh fails, tokens are cleared, auth.currentUser emits null, and the original call throws BunBaseError.Unauthenticated.

Auth state

Auth state is a StateFlow<AuthUser?> — integrate it directly with collectAsState() in Compose or lifecycleScope.launchWhenStarted in View-based UIs.

// ViewModel
val user = client.auth.currentUser // StateFlow<AuthUser?>

// Compose
val user by client.auth.currentUser.collectAsState()