spoo.me Kotlin SDK

val spoo = SpooClient(apiKey = "spoo_your_api_key")

val link = spoo.links.create {
    longUrl = "https://example.com/launch"
    alias = "launch" // or emoji: "🚀🔥"
    maxClicks = 10_000
}
println(link.shortUrl) // https://spoo.me/launch

dependencies {
    implementation("me.spoo:spoo:0.1.0")
}

val spoo = SpooClient(apiKey = "spoo_...")

val spoo = SpooClient(SpooConfig(
    apiKey = "spoo_...",
    baseUrl = "https://links.example.com",
    engine = OkHttp.create(),          // shared pools, proxies, tests
    clientTag = "my-app/1.0",          // X-Spoo-Client override
))

val link = spoo.links.create {
    longUrl = "https://example.com/launch"
    password = "secure@123"
    expireAfter = Clock.System.now() + 30.days
}

spoo.links.claim(listOf(ClaimRequest(urlId = link.id, token = link.claimToken!!)))

// Paginated listing with typed filters.
val page = spoo.links.list(ListLinksRequest(
    pageSize = 50,
    sortBy = SortBy.TOTAL_CLICKS,
    status = SettableStatus.ACTIVE,
    search = "promo",
))

// Or walk everything lazily.
spoo.links.listPaginated().items().collect { println(it.id) }

// Updates only touch what you set; remove* clears a setting explicitly.
spoo.links.update(link.id) {
    longUrl("https://example.com/v2")
    removePassword()
}

// Bulk operations report per-item outcomes instead of failing the batch.
val outcome = spoo.links.bulkSetStatus(ids, SettableStatus.INACTIVE)
outcome.results.filterNot { it.ok }.forEach { println("${it.id}: ${it.errorCode}") }

val report = spoo.stats.account(AccountStatsRequest(
    query = StatsQuery(
        groupBy = listOf(Dimension.TIME, Dimension.COUNTRY),
        filters = mapOf(FilterDimension.BROWSER to listOf("Chrome")),
    ),
))
println("${report.summary.totalClicks} clicks")

val perLink = spoo.stats.forLink(link.id)

// Exports stream; filenames from the server are reduced to a bare name
// (no separators or dot-segments), so joining one into a directory cannot
// traverse out of it. Choosing a safe directory remains your job.
val export = spoo.stats.exportLink(link.id, ExportFormat.CSV)
File(downloads, export.filename).writeBytes(export.bytes())

val anon = SpooClient()
val stats = anon.publicLinks.stats("launch")
val locked = anon.publicLinks.stats("locked", password = "hunter@22")
val preview = anon.publicLinks.preview("launch") // never reveals what the redirect refuses
val emoji = anon.emoji.set()                     // ETag-cached on the client

try {
    spoo.links.get("gone")
} catch (e: NotFoundException) {
    println("no such link")
} catch (e: RateLimitException) {
    println("wait ${e.rateLimit.retryAfter}")
} catch (e: ContentBlockedException) {
    println("taken down")
} catch (e: AuthenticationException) {
    if (e.isPasswordRequired) promptForLinkPassword()
}

val anon = SpooClient()
val pkce = generatePkcePair()
val state = generateState()
val url = anon.oauth.authorizationUrl(
    appId = "your_app_id",
    state = state,
    codeChallenge = pkce.challenge,
    redirectUri = "https://your.app/callback",
)
// Open url in a browser (Custom Tabs on Android); the callback carries
// code and state. Verify the echoed state matches BEFORE exchanging the
// code, and reject the flow on a mismatch.

val tokens = anon.oauth.exchangeCode(code, pkce.verifier)

val session = Session(tokens.tokens(), onRefresh = { pair ->
    // Persist the rotated pair: the previous refresh token is dead.
})
val spoo = SpooClient(session = session)
val me = spoo.auth.me()

@Serializable data class Whatever(val ok: Boolean)
val value: Whatever = spoo.get("/api/v1/new-endpoint", listOf("k" to "v"))