The official nRouter Node.js and TypeScript SDK with automatic metadata parsing, SSE streaming, server prompt templates, and client conversation memory.

The official nRouter Node.js SDK (@nrouter_ai/sdk) provides complete, first-class TypeScript bindings for the nRouter unified AI gateway (https://api.nrouter.ai/v1). It features automated extraction of x-nr-* response headers, real-time cost tracking, client-side conversation memory, server-side prompt templating, and full wire compatibility across both OpenAI and Anthropic models.

Deploying your Node.js or TypeScript applications through nRouter centralizes your AI infrastructure: server-side guardrails block prompt injection attempts before model processing, virtual keys enforce strict team budgets, and automatic failovers eliminate downtime across upstream provider outages.

Prerequisites & Installation

The SDK requires Node.js 18 or higher (LTS recommended) and supports Node.js, Next.js, Remix, Bun, and Deno environments.

Install @nrouter_ai/sdk from npm:

npm install @nrouter_ai/sdk

Or with your preferred package manager:

pnpm add @nrouter_ai/sdk
# or
yarn add @nrouter_ai/sdk
# or
bun add @nrouter_ai/sdk

Setup & Configuration

Configure authentication by setting your nRouter virtual key in your environment:

export NROUTER_API_KEY="sk-nrouter-your-virtual-key"

Basic Initialization

The client automatically resolves NROUTER_API_KEY from the environment and points to https://api.nrouter.ai/v1:

import { nRouter } from "@nrouter_ai/sdk";

// Automatically reads NROUTER_API_KEY from environment
const client = new nRouter();

Configuration Parameters

Configure connection timeouts, retries, and default routing directives:

Parameter	Type	Default	Description
`apiKey`	`string`	`process.env.NROUTER_API_KEY`	Your nRouter virtual key (`sk-nrouter-...`).
`baseURL`	`string`	`https://api.nrouter.ai/v1`	Unified gateway base URL. Must include `/v1`.
`timeout`	`number`	`60000`	Maximum request timeout in milliseconds.
`maxRetries`	`number`	`2`	Client-side retry limit. nRouter handles upstream provider retries automatically.
`defaultHeaders`	`Record<string, string>`	`{}`	Headers sent with every call (e.g. `x-nr-routing`).

import { nRouter } from "@nrouter_ai/sdk";

// Production client configuration with latency routing
const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
  baseURL: "https://api.nrouter.ai/v1",
  timeout: 45000,
  maxRetries: 3,
  defaultHeaders: {
    "x-nr-routing": "latency",
  },
});

Implementation Patterns

1. Synchronous Chat Completion

Send structured messages and inspect automated cost attribution:

import { nRouter } from "@nrouter_ai/sdk";

const client = new nRouter();

async function runCompletion() {
  const response = await client.chat.completions.create({
    model: "gpt-5.4-mini",
    messages: [
      { role: "system", content: "You are a cloud infrastructure engineer." },
      { role: "user", content: "Explain why HTTP keepalive matters for LLM proxies." },
    ],
  });

  console.log("Response:", response.choices[0].message.content);

  // Inspect auto-captured response telemetry
  if (client.lastResponse) {
    const { cost, costStatus, requestId, model, inputTokens, outputTokens } = client.lastResponse;
    console.log(`Model: ${model} | Request ID: ${requestId}`);
    console.log(`Cost: $${cost} (${costStatus}) | Tokens: ${inputTokens} in / ${outputTokens} out`);
  }
}

runCompletion();

2. Real-time Streaming (SSE)

Stream tokens using standard async iterables:

import { nRouter } from "@nrouter_ai/sdk";

const client = new nRouter();

async function streamResponse() {
  const stream = await client.chat.completions.create({
    model: "claude-haiku-4-5-20251001",
    messages: [{ role: "user", content: "Write a concise poem about distributed consensus." }],
    stream: true,
  });

  for await (const chunk of stream) {
    const delta = chunk.choices[0]?.delta?.content || "";
    process.stdout.write(delta);
  }
  console.log();
}

streamResponse();

3. Multi-Turn Conversation Memory

Use createMemory() to maintain message context client-side without storing state on intermediate gateways:

import { nRouter, createMemory } from "@nrouter_ai/sdk";

const client = new nRouter();
const memory = createMemory({ maxMessages: 10 });

async function chat() {
  memory.add("user", "My name is David and I am building an automated trading engine.");
  const res1 = await client.nr.chat({
    model: "gpt-5.4-mini",
    messages: memory.messages(),
  });
  memory.add("assistant", client.nr.text(res1));

  memory.add("user", "What architecture did I say I am building?");
  const res2 = await client.nr.chat({
    model: "gpt-5.4-mini",
    messages: memory.messages(),
  });
  console.log(client.nr.text(res2));
}

chat();

4. Server-Side Prompt Templates

Combine dashboard prompt templates with dynamic variables:

import { nRouter, promptTemplate } from "@nrouter_ai/sdk";

const client = new nRouter();

async function runTemplate() {
  const response = await client.nr.chat(
    promptTemplate(
      "tmpl_customer_onboarding_v1",
      { user_role: "Tech Lead", plan: "Enterprise" },
      {
        model: "gpt-5.4-mini",
        messages: [{ role: "user", content: "Show me my workspace dashboard." }],
      }
    )
  );

  console.log(client.nr.text(response));
}

runTemplate();

5. Plain OpenAI Client Drop-in

If your project standardizes on the official openai npm package without additional wrappers:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NROUTER_API_KEY,
  baseURL: "https://api.nrouter.ai/v1",
});

async function main() {
  const response = await client.chat.completions.create({
    model: "gpt-5.4-mini",
    messages: [{ role: "user", content: "Hello from standard OpenAI client!" }],
  });
  console.log(response.choices[0].message.content);
}

main();

Production Best Practices

Deterministic Routing & Fallbacks

Ensure application availability during cloud provider outages:

const response = await client.chat.completions.create({
  // Specify primary and secondary models
  model: "gpt-5.4-mini,claude-haiku-4-5-20251001",
  messages: [{ role: "user", content: "Analyze transaction anomaly" }],
  headers: {
    "x-nr-routing": "latency",
  },
});

x-nr-routing: latency: Directs requests to the fastest cloud region and provider.
x-nr-routing: cost: Ensures execution on the lowest-cost available provider deployment.
Automatic Fallback: If the primary provider reports 5xx errors or capacity exhaustion, nRouter fails over seamlessly to the secondary model.

Connection Reuse & Keep-Alive

In Node.js backend services, ensure your HTTP agent uses persistent keep-alive connections:

import http from "node:http";
import https from "node:https";
import { nRouter } from "@nrouter_ai/sdk";

const httpAgent = new https.Agent({
  keepAlive: true,
  maxSockets: 100,
  maxFreeSockets: 20,
  timeout: 60000,
});

const client = new nRouter({
  httpAgent,
});

Telemetry & FinOps Tracking

Every call through nRouter captures full accounting metadata on client.lastResponse:

cost: Exact USD cost incurred for the call.
costStatus: exact when fully priced, unpriced if provider unlisted.
requestId: Gateway-assigned trace UUID.
model: Canonical deployment identifier that served the tokens.
inputTokens / outputTokens: Token breakdown figures.

Troubleshooting & Error Handling

Errors map to descriptive HTTP status codes.

Common Error Codes

Status	Code	Cause	Recommended Action
`400`	`guardrail_blocked`	Input rejected by server-side content or injection guardrails	Verify prompt safety; review guardrail settings in nRouter dashboard.
`401`	`authentication_error`	Missing, incorrect, or expired virtual API key	Check `NROUTER_API_KEY` environment variable.
`402`	`insufficient_credits`	Zero organization balance or key spending limit reached	Add funds in dashboard or update key ceiling.
`429`	`rate_limit_exceeded`	Client exceeded RPM/TPM quota	Implement exponential backoff; check retry headers.
`500` / `503`	`service_unavailable`	Downstream provider error or network disruption	Use fallback model lists (`model1,model2`).

Error Catching Pattern

import { nRouter, APIError } from "@nrouter_ai/sdk";

const client = new nRouter();

try {
  const res = await client.chat.completions.create({
    model: "gpt-5.4-mini",
    messages: [{ role: "user", content: "Run analysis" }],
  });
} catch (error) {
  if (error instanceof APIError) {
    switch (error.status) {
      case 400:
        console.error("Bad request or guardrail rejection:", error.message);
        break;
      case 401:
        console.error("Authentication failed: Check NROUTER_API_KEY");
        break;
      case 402:
        console.error("Payment required: Organization balance exhausted");
        break;
      case 429:
        console.error("Rate limit reached. Backing off before retry.");
        break;
      default:
        console.error(`Gateway error [${error.status}]:`, error.message);
    }
  } else {
    console.error("Network or unexpected error:", error);
  }
}

Certified SDK Examples

The official SDK repository includes battle-tested examples:

Topic	Example File	Description
Quickstart	`quickstart.ts`	First-run TypeScript starter
Complete Showcase	`node.ts`	Multi-turn memory, prompt templates, conflict resolution
Vercel AI SDK	`vercel_ai.ts`	Integration with Vercel AI SDK (`@ai-sdk/openai`)
E2E Suite	`demo_e2e_suite.js`	Certified end-to-end multi-language test

Next Steps

Vercel AI SDK Integration — Next.js and React streaming UI
Python SDK Guide — Official nRouter Python SDK
Chat Completions API — Direct HTTP wire specifications

TypeScript / Node.js SDK