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")
]
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
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)
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: "")
}
}
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)