{"slug": "coroutines-first-notes-on-nrouter-s-kotlin-sdk", "title": "Coroutines first: notes on nRouter's Kotlin SDK", "summary": "NRouter released a coroutines-first Kotlin SDK (ai.nrouter:nrouter-sdk-kotlin:3.1.2) for its API gateway, using suspend functions for calls and a cold Flow for streaming responses. The client reads NROUTER_API_KEY from the environment, dispatches on Dispatchers.IO, exposes gateway routing preferences like nrouter_optimize and nrouter_cost_band in the request payload, and surfaces x-nr-* header metadata as typed fields. Gateway refusals map to typed NRouterError subclasses with an isRetryable flag that is true for RateLimit, Service and Transport errors.", "body_md": "A Kotlin client for an API gateway can be a thin wrapper around blocking HTTP calls, with a coroutine adapter bolted on. The nRouter Kotlin guide goes the other way: the SDK is coroutines-first from the start — suspend functions for calls, a cold `Flow` for streaming, and typed error subclasses you can branch on.\n\nFull guide: [https://nrouter.ai/docs/sdks/kotlin](https://nrouter.ai/docs/sdks/kotlin)\n\nThe guide publishes the artifact to your local Maven cache (`./gradlew clean check publishToMavenLocal`), then it's a normal Gradle dependency:\n\n```\ndependencies {\n    implementation(\"ai.nrouter:nrouter-sdk-kotlin:3.1.2\")\n}\n```\n\n`NRouter()` reads `NROUTER_API_KEY` from the environment, targets `https://api.nrouter.ai/v1`, and dispatches on `Dispatchers.IO`, so calls don't block your caller's context. (For Android apps, the guide points to the separate `nrouter-sdk-android` artifact.)\n\n```\nsuspend fun main() {\n    val client = NRouter()\n\n    val result = client.chatCompletions(\n        JSONObject()\n            .put(\"model\", \"nrouter/auto\")\n            .put(\"messages\", listOf(mapOf(\"role\" to \"user\", \"content\" to \"Hello!\")))\n            .put(\"nrouter_optimize\", \"balanced\")\n    )\n\n    val content = result.body.getJSONArray(\"choices\")\n        .getJSONObject(0).getJSONObject(\"message\").getString(\"content\")\n    println(content)\n    println(\"Request ID: ${result.meta.requestId}\")\n}\n```\n\nTwo things worth noticing. The routing preference rides in the payload: `\"nrouter/auto\"` plus `\"nrouter_optimize\"` (`quality`, `balanced` or `cost`), with `\"nrouter_cost_band\"` (`low`, `mid`, `high`) available under `cost`. And the response carries `.meta` extracted from the gateway's `x-nr-*` headers, so request ID and cost metadata arrive as typed fields instead of header strings you parse yourself.\n\nStreaming is a cold Flow — nothing moves until you collect:\n\n```\nclient.messagesStream(\n    JSONObject()\n        .put(\"model\", \"nrouter/auto\")\n        .put(\"messages\", listOf(mapOf(\"role\" to \"user\", \"content\" to \"Hello!\")))\n).collect { chunk ->\n    print(chunk.delta)\n}\n```\n\nCold matters here: the request starts on collection and stops when the collector goes away, which is exactly the lifecycle behaviour you want in a view model or a Ktor handler.\n\nGateway refusals map to subclasses of `NRouterError`: `Request` (400, including `cost_band_unsatisfiable`), `GuardrailBlocked` (400), `Authentication` (401), `Credit` (402), `RateLimit` (429) and `Service` (503). The detail that makes this practical is `isRetryable` — true for `RateLimit`, `Service` and `Transport` — so a retry policy is one `when` branch instead of a table of status codes maintained by hand.\n\nThat's the whole shape: a JVM client that treats coroutines as the default rather than an add-on, and lets the gateway carry routing, budgets and guardrails behind one key. The guide has the full walkthrough: [https://nrouter.ai/docs/sdks/kotlin](https://nrouter.ai/docs/sdks/kotlin)", "url": "https://wpnews.pro/news/coroutines-first-notes-on-nrouter-s-kotlin-sdk", "canonical_source": "https://dev.to/nrouterai/coroutines-first-notes-on-nrouters-kotlin-sdk-559n", "published_at": "2026-11-19 13:08:57+00:00", "updated_at": "2026-11-19 13:14:20.787468+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-infrastructure", "large-language-models"], "entities": ["nRouter", "Kotlin", "Gradle", "Maven", "Ktor"], "also_reported_by": [], "takeaway": "The nRouter Kotlin SDK makes streaming a cold Flow that starts on collection and cancels with the collector, and marks RateLimit, Service and Transport errors as retryable via isRetryable so retry policy is a single when branch.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/coroutines-first-notes-on-nrouter-s-kotlin-sdk", "markdown": "https://wpnews.pro/news/coroutines-first-notes-on-nrouter-s-kotlin-sdk.md", "text": "https://wpnews.pro/news/coroutines-first-notes-on-nrouter-s-kotlin-sdk.txt", "jsonld": "https://wpnews.pro/news/coroutines-first-notes-on-nrouter-s-kotlin-sdk.jsonld"}}