BosBase Kotlin SDK

Official Kotlin SDK for interacting with the BosBase API. This module mirrors the JavaScript SDK surface so JVM and Android apps can talk to the BosBase HTTP API with a small, coroutine-friendly wrapper built on OkHttp and kotlinx.serialization.

Quick Start

import com.bosbase.sdk.BosBase

val pb = BosBase("http://127.0.0.1:8090")

// Authenticate against an auth collection
val auth = pb.collection("users").authWithPassword("test@example.com", "123456")
println(auth["token"])

// List records with filter/expand
val posts = pb.collection("posts").getList(page = 1, perPage = 10, expand = "author")
posts.items.forEach { post ->
    println(post["title"])
}

// Create a record (files supported via FileAttachment)
pb.collection("posts").create(
    mapOf("title" to "Hello Kotlin!")
)

📖 New to BosBase? Check out the Quick Start Guide to get up and running in minutes!

Documentation

Comprehensive documentation is available in the docs/ directory:

• Quick Start Guide - Get started in minutes
• Authentication - User authentication, OAuth2, OTP, password reset
• API Records - CRUD operations, filtering, sorting, relations
• Collections - Collection management, fields, indexes, API rules
• Files - File uploads, downloads, thumbnails, protected files
• Realtime - Real-time subscriptions and live updates
• SQL Execution - Superuser SQL execution helper
• Custom Token Auth - Bind/unbind tokens and authenticate with them

📚 Reference: The Kotlin SDK mirrors the JavaScript SDK API. For additional examples and concepts, see the JavaScript SDK documentation.

Key Features

• BosBase.send(...) thin HTTP wrapper with beforeSend/afterSend hooks and auth header injection
• pb.collection("name") exposes record CRUD, auth helpers (authWithPassword, authRefresh, OTP), and convenience counters
• pb.collections exposes collection CRUD plus scaffold helpers (createBase, createAuth, createView)
• pb.files builds download URLs and requests private file tokens
• Services mirror the JS SDK: collections, records, logs, realtime, health, backups, crons, vectors, LLM documents, LangChaingo, caches, settings, and transactional batch operations
• Custom auth flows: bind/unbind tokens (bindCustomToken, unbindCustomToken), token login (authWithToken), and automatic token refresh for superusers
• Superuser SQL execution via pb.sql.execute() to run ad-hoc SQL through /api/sql/execute
• Filter helper pb.filter("title ~ {:title}", mapOf("title" to "demo")) mirrors the JS SDK escaping rules
• Multipart uploads via FileAttachment.fromFile(...) or FileAttachment(filename, bytes, contentType)
• Persistent auth stores (LocalAuthStore, AsyncAuthStore) for JVM and Android
• Automatic token refresh and reconnection handling

Installation

Gradle (Kotlin DSL)

dependencies {
    implementation("com.bosbase:bosbase-kotlin-sdk:0.1.0")
}

Gradle (Groovy)

dependencies {
    implementation 'com.bosbase:bosbase-kotlin-sdk:0.1.0'
}

Maven

<dependency>
    <groupId>com.bosbase</groupId>
    <artifactId>bosbase-kotlin-sdk</artifactId>
    <version>0.1.0</version>
</dependency>

Requirements

• Kotlin: 1.8.0+
• Java: 11+
• Gradle: 8.x (for building)

The SDK is compatible with:

• JVM applications (desktop/server)
• Android applications
• Any Kotlin/JVM project

Examples

Authentication

import com.bosbase.sdk.BosBase

val pb = BosBase("http://localhost:8090")

// Password authentication
val authData = pb.collection("users").authWithPassword(
    identity = "user@example.com",
    password = "password123"
)

// Check auth status
println(pb.authStore.isValid)  // true
println(pb.authStore.token)     // JWT token

// Logout
pb.authStore.clear()

CRUD Operations

// Create
val newPost = pb.collection("posts").create(
    body = mapOf(
        "title" to "My Post",
        "content" to "Post content"
    )
)

// Read
val post = pb.collection("posts").getOne("RECORD_ID")

// List with filter
val results = pb.collection("posts").getList(
    page = 1,
    perPage = 50,
    filter = "status = 'published'",
    sort = "-created"
)

// Update
val updated = pb.collection("posts").update(
    id = "RECORD_ID",
    body = mapOf("title" to "Updated Title")
)

// Delete
pb.collection("posts").delete("RECORD_ID")

File Upload

import com.bosbase.sdk.FileAttachment
import java.io.File

val attachment = FileAttachment.fromFile(File("image.jpg"))

val record = pb.collection("posts").create(
    body = mapOf("title" to "Post with Image"),
    files = mapOf("image" to listOf(attachment))
)

Realtime Subscriptions

val unsubscribe = pb.collection("posts").subscribe("*") { event ->
    val action = event["action"]?.toString()  // 'create', 'update', 'delete'
    val record = event["record"]
    println("$action: $record")
}

// Later...
unsubscribe()

For more examples, see the documentation.

Building Locally

The module uses Gradle with the Kotlin DSL. From kotlin-sdk/:

gradle build  # or ./gradlew build if you add a wrapper

The resulting JVM artifact targets Java 11+. The code avoids Android-specific APIs so it works in both server and Android projects when packaged.

Publishing

This library is published to Maven Central. For instructions on how to publish new versions, see PUBLISHING.md.

Current Version

The current published version is 0.1.0. Check Maven Central for the latest version.

License

See LICENSE file for details.