DEV Community

nRouter
nRouter

Posted on

Zero dependencies: notes on nRouter's Swift SDK

Adding AI calls to an iOS or macOS app usually goes one of two ways. You hand-roll URLSession code and maintain it forever, or you pull in a client library that drags its own dependency tree along. The Swift guide for nRouter takes a narrower path: an official Swift package with zero third-party dependencies, built on URLSession and structured concurrency.

Full guide: https://nrouter.ai/docs/sdks/swift

The package

It's a Swift Package Manager dependency, so setup is one line in Package.swift (or File → Add Package Dependencies in Xcode):

dependencies: [
    .package(url: "https://github.com/nRouterGateway/nrouter-sdk.git", from: "2.2.1")
]
Enter fullscreen mode Exit fullscreen mode

The client reads NROUTER_API_KEY from the environment, which suits CLI tools and macOS apps, or you pass the key directly on iOS:

import NRouter

let client = try NRouter(apiKey: "...") // or try NRouter() from env
Enter fullscreen mode Exit fullscreen mode

It talks to https://api.nrouter.ai/v1 and covers iOS 15+, macOS 12+, watchOS 8+ and visionOS 1+.

Calls are payloads, errors are typed

A chat call takes a plain dictionary and awaits the result:

let payload: [String: Any] = [
    "model": "nrouter/auto",
    "messages": [["role": "user", "content": "Explain Swift concurrency."]],
    "max_completion_tokens": 512
]

let result = try await client.chatCompletions(payload)
Enter fullscreen mode Exit fullscreen mode

Streaming returns an AsyncThrowingStream, so consuming tokens is just a loop:

let stream = try await client.chatCompletionsStream([
    "model": "nrouter/auto",
    "messages": [["role": "user", "content": "Write a haiku."]],
    "stream": true
])

for try await chunk in stream {
    if let delta = chunk.deltaContent {
        print(delta, terminator: "")
    }
}
Enter fullscreen mode Exit fullscreen mode

Two details stand out if you've wired this up by hand before.

First, routing preference rides in the payload. Send "model": "nrouter/auto" and add "nrouter_optimize" (quality, balanced or cost) per call; under cost you can pin "nrouter_cost_band" to low, mid or high. The app states its preference per request instead of hardcoding a model choice it then has to revisit.

Second, failures arrive as NRouterError cases, not as a JSON body you parse defensively. The guide's switch covers .request (including cost_band_unsatisfiable), .guardrailBlocked, .authentication, .credit and .budgetExceeded, .rateLimit carrying a retryAfter, and .service. A rate limit telling you exactly how long to back off is a small thing that saves a lot of guessing in retry code.

Why the zero-dependency part matters

On Apple platforms, every dependency is a future version conflict, a longer build, and one more thing to audit. A gateway client that sits on URLSession and the standard library has almost no surface to break when the OS moves. The SDK is a thin, typed layer over one endpoint, and that's the right shape for infrastructure code in an app binary.

The guide walks the whole flow, including the full error table: https://nrouter.ai/docs/sdks/swift

Top comments (0)