InsForge Kotlin SDK

Official Kotlin SDK for InsForge - A modern Backend-as-a-Service platform.

Features

• 🔐 Authentication - Email/password, OAuth, email verification, password reset
• 📊 Database - PostgREST-style API with type-safe queries
• 📦 Storage - S3-compatible object storage with presigned URLs
• ⚡ Functions - Serverless functions in Deno runtime
• 🔄 Realtime - WebSocket pub/sub channels via Socket.IO
• 🤖 AI - Chat completion and image generation via OpenRouter

Installation

Maven Central (Recommended)

// build.gradle.kts
dependencies {
    implementation("dev.insforge:insforge-kotlin:0.1.2")
}

GitHub Packages

// build.gradle.kts
repositories {
    maven {
        url = uri("https://maven.pkg.github.com/InsForge/insforge-kotlin")
        credentials {
            username = "your-github-username"
            password = "your-github-token"  // needs read:packages permission
        }
    }
}

dependencies {
    implementation("dev.insforge:insforge-kotlin:0.1.2")
}

Build from Source

git clone https://github.com/InsForge/insforge-kotlin.git
cd insforge-kotlin
./gradlew publishToMavenLocal

// build.gradle.kts
repositories {
    mavenLocal()
}

dependencies {
    implementation("dev.insforge:insforge-kotlin:0.1.2-SNAPSHOT")
}

Quick Start

import dev.insforge.createInsforgeClient
import dev.insforge.auth.*
import dev.insforge.database.*
import dev.insforge.storage.*
import dev.insforge.functions.*
import dev.insforge.realtime.*
import dev.insforge.ai.*

val client = createInsforgeClient(
    baseURL = "https://your-project.insforge.io",
    anonKey = "your-anon-key"
) {
    install(Auth)
    install(Database)
    install(Storage)
    install(Functions)
    install(Realtime)
    install(AI)
}

// Authentication
client.auth.signIn("user@example.com", "password123")

// Database - typed queries
@Serializable
data class Post(val id: String, val title: String, val published: Boolean)

val posts = client.database.from("posts")
    .select()
    .eq("published", true)
    .execute<Post>()

// Database - raw queries (for joins/nested data)
val rawData = client.database.from("posts")
    .select("id,title,author!posts_author_id_fkey(name)")
    .executeRaw()

// Storage
val result = client.storage.from("images").upload("photo.jpg", bytes) {
    contentType = "image/jpeg"
}

// Functions
val response = client.functions.invoke<MyResponse>("hello-world", request)

// Realtime
client.realtime.connect()
client.realtime.subscribe("chat:room1")
client.realtime.on("message") { msg ->
    println(msg.payload)
}

// AI
val chatResponse = client.ai.chatCompletion(
    model = "openai/gpt-4",
    messages = listOf(ChatMessage("user", "Hello!"))
)

Documentation

• 📖 Getting Started - Quick start guide with detailed examples

Project Structure

src/main/kotlin/dev/insforge/
├── InsforgeClient.kt          # Core client
├── auth/                      # Authentication module
├── database/                  # Database module
├── storage/                   # Storage module
├── functions/                 # Functions module
├── realtime/                  # Realtime module
├── ai/                        # AI module
├── plugins/                   # Plugin system
├── http/                      # HTTP client (Ktor + OkHttp)
├── logging/                   # Logging (Napier)
└── exceptions/                # Error handling

Build & Development

# Build
./gradlew clean build

# Run tests
./gradlew test

# Publish to local Maven
./gradlew publishToMavenLocal

Release Process

To create a new release and publish to Maven Central:

# 1. Ensure all changes are committed
git add .
git commit -m "your commit message"

# 2. Create release (auto-increments version, creates tag, pushes to remote)
./gradlew release

# 3. Create GitHub Release (triggers CI to publish to Maven Central)
gh release create v$(./gradlew currentVersion -q) \
    --title "v$(./gradlew currentVersion -q)" \
    --generate-notes

Or as a single command:

./gradlew release && gh release create v$(./gradlew currentVersion -q) --title "v$(./gradlew currentVersion -q)" --generate-notes

Requirements

• Java 11+
• Kotlin 1.9.22+

Tech Stack

Component	Technology	Version
Language	Kotlin	1.9.22
HTTP Client	Ktor + OkHttp	2.3.7
JSON	Kotlinx Serialization	1.6.2
Async	Kotlinx Coroutines	1.7.3
Logging	Napier	2.7.1
Realtime	Socket.IO	2.1.1

Modules

Module	Features
Auth	Sign up/in, Email verification, Password reset, OAuth, Session persistence
Database	CRUD, Query builder, Type-safe queries, Raw queries for joins
Storage	Upload/Download, Buckets, Presigned URLs, S3 compatible
Functions	Invoke serverless functions
Realtime	Pub/sub channels, Connection state management
AI	Chat completion, Image generation, Streaming

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Links

• InsForge Platform
• GitHub Repository
• Maven Central