Kotlin Alerts SDK

The API Alerts Kotlin SDK is built on Kotlin Multiplatform and runs everywhere Kotlin runs. Drop it into Android apps, Ktor servers, Spring Boot services, or any Kotlin codebase that needs to notify you when something important happens. Minimal setup, fire-and-forget by default with optional response handling, and zero infrastructure.

Installation

Add the dependency to your build.gradle.kts:

dependencies {
    implementation("com.apialerts:client:1.2.0")
}

Usage

Configure the singleton once at startup, then send from anywhere. For dependency injection, mocking, or multiple keys, use the instance client instead.

Fire and forget

import com.apialerts.client.ApiAlerts
import com.apialerts.client.Event

ApiAlerts.configure("your-api-key")

// Never throws, safe to call anywhere
ApiAlerts.send(Event(message = "Deploy complete"))

Wait for response

val result = ApiAlerts.sendAsync(Event(
    message = "New user signed up",
    channel = "revenue",
    event   = "user.signup",
    title   = "New Signup",
    tags    = listOf("growth", "organic"),
    link    = "https://dashboard.example.com/users/123",
    data    = mapOf("plan" to "pro"),
))

result.onSuccess { println("Sent to ${it.workspace} (${it.channel})") }
result.onFailure { println("Error: ${it.message}") }

DSL style

ApiAlerts.send {
    message = "Deploy complete"
    channel = "releases"
    event   = "ci.deploy"
    tags    = listOf("CI/CD")
    data    = mapOf("commit" to "a1b2c3d")
}

data takes a plain Map everywhere - the Event constructor, the DSL, and the Java EventBuilder - and the values are mapped to JSON for you. When you need full control over the JSON shape, pass a kotlinx.serialization.json.JsonObject (it is itself a Map, so the same data accepts it):

import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

ApiAlerts.send(Event(
    message = "Deploy complete",
    data    = buildJsonObject { put("plan", "pro") },
))

Dependency injection

Construct an ApiAlertsClient and inject it when you use DI, mock in tests, or need multiple keys:

import com.apialerts.client.ApiAlertsClient

// Koin
single<ApiAlertsClient> { ApiAlertsClient(apiKey = "your-api-key") }

class DeployNotifier(private val alerts: ApiAlertsClient) {
    suspend fun onDeploy() = alerts.sendAsync { message = "Deploy complete" }
}

ApiAlertsClient has the same send / sendAsync (plus the DSL) as the singleton - ApiAlerts is a thin facade over a default instance.

Multiple workspaces

Pass apiKey to override the configured key for a single call:

ApiAlerts.sendAsync(Event(message = "Cross-workspace event"), apiKey = "other-api-key")
    .onSuccess { println("Sent to ${it.workspace} (${it.channel})") }
    .onFailure { println("Error: ${it.message}") }

Event Fields

Field	Type	Required	Description
message	String	Yes	Notification text shown on the push lock screen.
channel	String?	No	Workspace channel; defaults to the workspace default.
event	String?	No	Routing key. Matched with Unix glob/fnmatch (ci.*, User *); dotted notation is a convention, not required.
title	String?	No	Short headline some destinations render separately.
tags	List<String>?	No	Categorisation tags.
link	String?	No	URL attached to the notification.
data	Map<String, Any?>?	No	Arbitrary metadata for non-push destination templating. Pass a JsonObject for full control over the JSON shape.

Resources