nrouter library
nRouter SDK — one API key for models across six provider clouds.
Works unchanged in Flutter (mobile, desktop, web) and plain Dart.
Classes
- ArrayMemoryStore
- MemoryStore
- NRouter
- nRouter client — one API key for models across six provider clouds.
- NRouterErrorBody
- The parsed gateway error payload plus the metadata worth acting on.
- NRouterErrorEnvelope
- Structured gateway error envelope.
- NRouterMemory
- NRouterResponse
- A body paired with the metadata the gateway reported for it.
- NRouterResponseMeta
-
Per-request metadata carried on the
x-nr-*response headers. - NRouterStreamChunk
- One decoded server-sent event from a streaming text request.
- PromptSelection
- RenderPromptOptions
Extensions
- VideoPolling on NRouter
- Extension providing polling helpers on the NRouter client.
Constants
- maxRetryAfterSeconds → const int
- Max Retry-After ceiling (24 hours).
- neutralTopP → const double
- promptTemplateIdField → const String
- promptVariablesField → const String
-
promptWireFields
→ const List<
String> -
systemVariableNames
→ const List<
String> -
validAudioFormats
→ const List<
String> - Supported audio formats for speech generation.
Functions
-
buildSamplingParams(
{required bool advanced, required String model, String? provider, double? temperature, double? topP}) → Map< String, double> - Implements Claude sampling policy: mutual exclusion between temperature and top_p.
-
computeJitteredBackoff(
{required int attempt, Duration baseDelay = const Duration(milliseconds: 500), Duration maxDelay = const Duration(seconds: 30), int? retryAfterSeconds, double jitterFactor = 0.5}) → Duration - Computes a bounded jittered exponential backoff duration.
-
extractTraceHeaders(
NRouterResponseMeta meta) → Map< String, String> -
Extract trace routing headers (e.g.
x-nr-request-id) from response metadata. -
extractTraceHeadersFromMap(
Map< String, String> headers) → Map<String, String> - Extract trace routing headers from an arbitrary map of HTTP headers.
-
formatNRouterError(
NRouterError error) → String - Formats an NRouterError into a human-readable, log-safe diagnostic string, masking all API keys.
-
isClaudeModel(
String model, [String? provider]) → bool - Returns true if the model or provider indicates an Anthropic Claude model.
-
parseGatewayErrorEnvelope(
Map< String, dynamic> raw) → NRouterErrorEnvelope - Parses a gateway error JSON payload into a structured NRouterErrorEnvelope.
-
parseRetryAfter(
String? raw, [DateTime? now]) → int? - Parses an RFC 9110 Retry-After header value (delta-seconds or HTTP-date).
-
promptTemplate(
String id, [Map< String, dynamic> ? variables]) → PromptSelection -
promptVariables(
Map< String, dynamic> variables) → PromptSelection -
redactKeys(
String s) → String - Redacts nRouter and upstream provider API keys to prevent credential leaks.
-
renderPrompt(
String template, [Map< String, dynamic> ? variables, RenderPromptOptions options = const RenderPromptOptions()]) → String -
Safely renders a prompt template by interpolating
{{variable}}or{{ variable }}tokens. -
slidingWindow(
List< ChatMessage> messages, int maxMessages, {bool preserveSystem = true}) → List<ChatMessage> - Prunes a list of messages to the most recent maxMessages, preserving index 0 system/developer message by default.
-
systemVariableConflicts(
Map< String, dynamic> ? variables) → List<String> -
validateAudioFormat(
String format) → void - Validates an audio format string.
-
withTraceContext(
Map< String, String> headers, {String? traceId, String? sessionId}) → Map<String, String> - Inject trace context headers, validating that traceId and sessionId do not contain CRLF characters.
Typedefs
-
ChatMessage
= Map<
String, dynamic> -
NRouterBinaryResponse
= ({List<
int> bytes, NRouterResponseMeta meta, int statusCode}) - Raw bytes paired with the metadata and status reported by the gateway.
Exceptions / Errors
- NRouterAuthenticationError
-
invalid_api_key(401) — virtual-key authentication refused. - NRouterBudgetExceededError
- A BUDGET ceiling (402), not a shortfall.
- NRouterConfigurationError
- The SDK refused before sending anything: no key, or a key that is not shaped like an nRouter key.
- NRouterCreditError
-
insufficient_credits(402) — the credit reserve failed. - NRouterError
- Why the gateway refused a request.
- NRouterGuardrailBlockedError
-
guardrail_blocked(400) — a guardrail rule denied the request. - NRouterNotFoundError
-
model_not_found(404) — alias absent or invisible to this tenant. - NRouterOtherError
- A code this SDK version does not know. Deliberately not re-classified.
- NRouterRateLimitError
-
rate_limit_exceeded/tpm_limit_exceeded(429). - NRouterRequestError
-
invalid_request(400) — invalid JSON or request shape. - NRouterServiceError
-
credit_check_failed/service_unavailable(503). - NRouterTransportError
- The request left this process and got no answer — DNS, TLS, a dropped connection, a timeout. Retryable.