diff --git a/README.md b/README.md
index 63dfcba..40c58ec 100644
--- a/README.md
+++ b/README.md
@@ -2,31 +2,30 @@
 
 The [OpenRouter](https://openrouter.ai/) provider for the [Vercel AI SDK](https://sdk.vercel.ai/docs) gives access to over 300 large language models on the OpenRouter chat and completion APIs.
 
-## Setup for AI SDK v5
+## Overview
 
-```bash
-# For pnpm
-pnpm add @openrouter/ai-sdk-provider
+This provider allows you to use the Vercel AI SDK with the OpenRouter API. It provides a seamless integration, allowing you to leverage the power of OpenRouter's extensive model catalog with the convenience of the AI SDK.
 
-# For npm
-npm install @openrouter/ai-sdk-provider
+## Features
 
-# For yarn
-yarn add @openrouter/ai-sdk-provider
-```
+- **Access to over 300 models**: Use any of the models available on OpenRouter, including the latest open-source and proprietary models.
+- **Chat and completion APIs**: Use both the chat and completion APIs, with support for streaming and non-streaming responses.
+- **Tool support**: Use tools with supported models to build powerful applications.
+- **Usage accounting**: Track your token usage and costs with OpenRouter's usage accounting feature.
+- **Anthropic prompt caching**: Leverage Anthropic's prompt caching for faster and cheaper responses.
+- **Provider routing**: Control how your requests are routed to different providers.
 
-## (LEGACY) Setup for AI SDK v4
+## Setup
 
 ```bash
 # For pnpm
-pnpm add @openrouter/ai-sdk-provider@ai-sdk-v4
+pnpm add @openrouter/ai-sdk-provider
 
 # For npm
-npm install @openrouter/ai-sdk-provider@ai-sdk-v4
+npm install @openrouter/ai-sdk-provider
 
 # For yarn
-yarn add @openrouter/ai-sdk-provider@ai-sdk-v4
-
+yarn add @openrouter/ai-sdk-provider
 ```
 
 ## Provider Instance
@@ -37,6 +36,17 @@ You can import the default provider instance `openrouter` from `@openrouter/ai-s
 import { openrouter } from '@openrouter/ai-sdk-provider';
 ```
 
+You can also create your own provider instance with custom settings:
+
+```ts
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+
+const openrouter = createOpenRouter({
+  apiKey: 'YOUR_API_KEY',
+  baseURL: 'https://my-proxy.com/api/v1',
+});
+```
+
 ## Example
 
 ```ts
@@ -197,3 +207,7 @@ if (result.providerMetadata?.openrouter?.usage) {
   );
 }
 ```
+
+## API Reference
+
+The full API reference is available in the [generated documentation](<LINK_TO_GENERATED_DOCS>).
diff --git a/e2e/tools.ts b/e2e/tools.ts
index c672e9f..2310cf6 100644
--- a/e2e/tools.ts
+++ b/e2e/tools.ts
@@ -9,6 +9,9 @@ const openrouter = createOpenRouter({
   baseUrl: `${process.env.OPENROUTER_API_BASE}/api/v1`,
 });
 
+/**
+ * A tool for sending an SMS message.
+ */
 export const sendSMSTool = tool({
   description: 'Send an SMS to any phone number',
   inputSchema: z.object({
@@ -24,6 +27,9 @@ export const sendSMSTool = tool({
   },
 });
 
+/**
+ * A tool for reading an SMS message.
+ */
 export const readSMSTool = tool({
   description: 'Read the nth SMS from a phone number',
   inputSchema: z.object({
@@ -39,6 +45,9 @@ export const readSMSTool = tool({
   },
 });
 
+/**
+ * A tool for executing a command in the terminal.
+ */
 export const executeCommandInTerminalTool = tool({
   description: 'Execute a command in the terminal',
   inputSchema: z.object({
diff --git a/examples/next-chat/.env.local.example b/examples/next-chat/.env.local.example
new file mode 100644
index 0000000..bcdf210
--- /dev/null
+++ b/examples/next-chat/.env.local.example
@@ -0,0 +1,5 @@
+# Required: obtain an API key from https://openrouter.ai/keys
+OPENROUTER_API_KEY=sk-or-...
+
+# Optional: override the base URL if you are pointing at a proxy.
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
diff --git a/examples/next-chat/README.md b/examples/next-chat/README.md
new file mode 100644
index 0000000..76a99cc
--- /dev/null
+++ b/examples/next-chat/README.md
@@ -0,0 +1,49 @@
+# OpenRouter Next.js Chat Example
+
+This example demonstrates how to build a streaming chat experience in Next.js using the
+[`@openrouter/ai-sdk-provider`](https://www.npmjs.com/package/@openrouter/ai-sdk-provider)
+and the Vercel AI SDK. The UI lets you:
+
+- pick an OpenRouter model
+- toggle tool usage on or off
+- watch streaming assistant replies
+- inspect tool invocations and their inputs/outputs in real time
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   pnpm install
+   pnpm --filter @openrouter/examples-next-chat dev
+   ```
+
+   > **Note:** the example is part of the monorepo. You can also `cd examples/next-chat`
+   > and run `pnpm install` followed by `pnpm dev`.
+
+2. Copy the example environment file and add your OpenRouter key:
+
+   ```bash
+   cp examples/next-chat/.env.local.example examples/next-chat/.env.local
+   ```
+
+   At minimum you need `OPENROUTER_API_KEY`. Set `OPENROUTER_BASE_URL` if you proxy requests.
+
+3. Start the development server:
+
+   ```bash
+   pnpm --filter @openrouter/examples-next-chat dev
+   ```
+
+   Visit `http://localhost:3000` to try the chat experience.
+
+## How It Works
+
+- `app/api/chat/route.ts` configures the OpenRouter provider, streams responses with tools, and
+  returns AI SDK UI message streams.
+- `app/page.tsx` implements a small client-side state machine that consumes the stream, renders
+  messages, and keeps track of tool invocations.
+- `lib/tools.ts` defines two sample tools (`getCurrentWeather` and `getCurrentTime`). You can add
+  your own tools or wire in real data sources.
+
+This example is intentionally lightweight so you can adapt it for your own projects.
diff --git a/examples/next-chat/app/api/chat/route.ts b/examples/next-chat/app/api/chat/route.ts
new file mode 100644
index 0000000..cf55968
--- /dev/null
+++ b/examples/next-chat/app/api/chat/route.ts
@@ -0,0 +1,65 @@
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import type { ModelMessage } from 'ai';
+import { streamText } from 'ai';
+
+import { BASIC_TOOLS } from '../../../lib/tools';
+import { DEFAULT_SYSTEM_PROMPT } from '../../../lib/models';
+
+interface ChatRequestBody {
+  modelId: string;
+  toolMode?: 'auto' | 'disabled';
+  messages: ModelMessage[];
+}
+
+const openrouter = createOpenRouter({
+  compatibility: 'strict',
+  baseURL: process.env.OPENROUTER_BASE_URL ?? process.env.OPENROUTER_API_BASE,
+});
+
+function normalizeToolMode(toolMode: ChatRequestBody['toolMode']) {
+  return toolMode === 'disabled' ? 'disabled' : 'auto';
+}
+
+export async function POST(request: Request) {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    return Response.json(
+      { error: 'Missing OPENROUTER_API_KEY environment variable.' },
+      { status: 500 },
+    );
+  }
+
+  let body: ChatRequestBody;
+  try {
+    body = (await request.json()) as ChatRequestBody;
+  } catch (_error) {
+    return Response.json({ error: 'Invalid JSON payload.' }, { status: 400 });
+  }
+
+  if (!body || typeof body.modelId !== 'string') {
+    return Response.json({ error: 'Request must include a modelId string.' }, { status: 400 });
+  }
+
+  if (!Array.isArray(body.messages) || body.messages.some((message) => typeof message !== 'object')) {
+    return Response.json({ error: 'Messages must be an array of chat messages.' }, { status: 400 });
+  }
+
+  const toolMode = normalizeToolMode(body.toolMode);
+  const shouldExposeTools = toolMode !== 'disabled';
+
+  try {
+    const result = streamText({
+      model: openrouter(body.modelId),
+      system: DEFAULT_SYSTEM_PROMPT,
+      messages: body.messages,
+      tools: shouldExposeTools ? BASIC_TOOLS : undefined,
+      toolChoice: shouldExposeTools ? 'auto' : 'none',
+    });
+
+    return result.toUIMessageStreamResponse();
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : 'Unknown error while contacting OpenRouter.';
+    return Response.json({ error: errorMessage }, { status: 500 });
+  }
+}
diff --git a/examples/next-chat/app/globals.css b/examples/next-chat/app/globals.css
new file mode 100644
index 0000000..eedeb41
--- /dev/null
+++ b/examples/next-chat/app/globals.css
@@ -0,0 +1,462 @@
+:root {
+  color-scheme: light dark;
+  font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  line-height: 1.5;
+  --surface-light: #ffffff;
+  --surface-dark: #0f172a;
+  --background-light: #f5f6fb;
+  --background-dark: #020617;
+  --text-muted-light: rgba(15, 23, 42, 0.65);
+  --text-muted-dark: rgba(226, 232, 240, 0.75);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background-color: var(--background-light);
+  color: #0f172a;
+}
+
+@media (prefers-color-scheme: dark) {
+  body {
+    background-color: var(--background-dark);
+    color: #f8fafc;
+  }
+}
+
+main {
+  min-height: 100vh;
+  display: flex;
+  justify-content: center;
+  padding: 2rem 1.5rem 3rem;
+}
+
+.container {
+  width: min(960px, 100%);
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+header {
+  text-align: center;
+}
+
+header h1 {
+  margin: 0;
+  font-size: clamp(1.8rem, 2.4vw + 1rem, 2.4rem);
+}
+
+.subtitle {
+  margin: 0.5rem 0 0;
+  color: var(--text-muted-light);
+}
+
+@media (prefers-color-scheme: dark) {
+  .subtitle {
+    color: var(--text-muted-dark);
+  }
+}
+
+.controls {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+}
+
+.control {
+  background-color: rgba(255, 255, 255, 0.88);
+  border: 1px solid rgba(15, 23, 42, 0.08);
+  border-radius: 12px;
+  padding: 1rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  box-shadow: 0 12px 30px rgba(15, 23, 42, 0.08);
+}
+
+@media (prefers-color-scheme: dark) {
+  .control {
+    background-color: rgba(15, 23, 42, 0.55);
+    border-color: rgba(148, 163, 184, 0.18);
+    box-shadow: 0 12px 30px rgba(0, 0, 0, 0.45);
+  }
+}
+
+label,
+.label {
+  font-weight: 600;
+  font-size: 0.8rem;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  color: rgba(15, 23, 42, 0.7);
+}
+
+@media (prefers-color-scheme: dark) {
+  label,
+  .label {
+    color: rgba(226, 232, 240, 0.85);
+  }
+}
+
+select,
+textarea,
+button {
+  font: inherit;
+}
+
+select,
+textarea {
+  width: 100%;
+  border-radius: 10px;
+  border: 1px solid rgba(15, 23, 42, 0.16);
+  padding: 0.6rem 0.75rem;
+  background-color: rgba(255, 255, 255, 0.96);
+  color: inherit;
+  transition: border-color 0.2s ease, box-shadow 0.2s ease;
+}
+
+textarea {
+  min-height: 120px;
+  resize: vertical;
+  line-height: 1.4;
+}
+
+select:focus,
+textarea:focus {
+  outline: none;
+  border-color: #2563eb;
+  box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.25);
+}
+
+select:disabled,
+textarea:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+@media (prefers-color-scheme: dark) {
+  select,
+  textarea {
+    background-color: rgba(15, 23, 42, 0.78);
+    border-color: rgba(148, 163, 184, 0.2);
+  }
+
+  select:focus,
+  textarea:focus {
+    border-color: #60a5fa;
+    box-shadow: 0 0 0 3px rgba(96, 165, 250, 0.25);
+  }
+}
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.2rem 0.6rem;
+  border-radius: 999px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  background-color: rgba(37, 99, 235, 0.12);
+  color: #1d4ed8;
+  border: 1px solid rgba(37, 99, 235, 0.18);
+  width: fit-content;
+}
+
+.badge.idle {
+  background-color: rgba(15, 23, 42, 0.08);
+  color: rgba(15, 23, 42, 0.75);
+  border-color: transparent;
+}
+
+.badge.status.collecting {
+  background-color: rgba(16, 185, 129, 0.12);
+  color: #047857;
+  border-color: rgba(16, 185, 129, 0.2);
+}
+
+.badge.status.running,
+.badge.status.complete {
+  background-color: rgba(59, 130, 246, 0.12);
+  color: #1d4ed8;
+  border-color: rgba(59, 130, 246, 0.2);
+}
+
+.badge.status.error {
+  background-color: rgba(239, 68, 68, 0.14);
+  color: #b91c1c;
+  border-color: rgba(239, 68, 68, 0.2);
+}
+
+@media (prefers-color-scheme: dark) {
+  .badge {
+    background-color: rgba(96, 165, 250, 0.18);
+    color: #bfdbfe;
+    border-color: rgba(96, 165, 250, 0.24);
+  }
+
+  .badge.idle {
+    background-color: rgba(148, 163, 184, 0.22);
+    color: rgba(226, 232, 240, 0.85);
+  }
+
+  .badge.status.collecting {
+    background-color: rgba(45, 212, 191, 0.24);
+    color: #5eead4;
+  }
+
+  .badge.status.running,
+  .badge.status.complete {
+    background-color: rgba(96, 165, 250, 0.24);
+    color: #bfdbfe;
+  }
+
+  .badge.status.error {
+    background-color: rgba(248, 113, 113, 0.22);
+    color: #fecaca;
+  }
+}
+
+.primary,
+.secondary {
+  border-radius: 999px;
+  border: none;
+  cursor: pointer;
+  font-weight: 600;
+  padding: 0.55rem 1.2rem;
+  transition: transform 0.15s ease, box-shadow 0.15s ease, opacity 0.15s ease;
+}
+
+.primary {
+  background: linear-gradient(135deg, #2563eb, #4f46e5);
+  color: #fff;
+  box-shadow: 0 10px 24px rgba(37, 99, 235, 0.35);
+}
+
+.primary:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  box-shadow: none;
+}
+
+.primary:not(:disabled):active {
+  transform: translateY(1px);
+}
+
+.secondary {
+  background-color: transparent;
+  border: 1px solid rgba(15, 23, 42, 0.2);
+  color: inherit;
+}
+
+.secondary:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+@media (prefers-color-scheme: dark) {
+  .secondary {
+    border-color: rgba(148, 163, 184, 0.35);
+  }
+}
+
+.chat-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  background-color: rgba(255, 255, 255, 0.92);
+  border: 1px solid rgba(15, 23, 42, 0.08);
+  border-radius: 16px;
+  padding: 1.5rem;
+  box-shadow: 0 24px 48px rgba(15, 23, 42, 0.12);
+}
+
+@media (prefers-color-scheme: dark) {
+  .chat-panel {
+    background-color: rgba(15, 23, 42, 0.65);
+    border-color: rgba(148, 163, 184, 0.2);
+    box-shadow: 0 24px 48px rgba(0, 0, 0, 0.4);
+  }
+}
+
+.alert {
+  padding: 0.75rem 1rem;
+  border-radius: 12px;
+  background-color: rgba(239, 68, 68, 0.14);
+  color: #991b1b;
+  border: 1px solid rgba(239, 68, 68, 0.2);
+}
+
+@media (prefers-color-scheme: dark) {
+  .alert {
+    background-color: rgba(239, 68, 68, 0.22);
+    color: #fecaca;
+  }
+}
+
+.chat-log {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  padding: 1rem;
+  border-radius: 12px;
+  border: 1px solid rgba(15, 23, 42, 0.08);
+  max-height: 420px;
+  overflow-y: auto;
+  background: rgba(248, 250, 252, 0.85);
+}
+
+@media (prefers-color-scheme: dark) {
+  .chat-log {
+    background: rgba(30, 41, 59, 0.62);
+    border-color: rgba(148, 163, 184, 0.16);
+  }
+}
+
+.empty {
+  margin: 0;
+  color: rgba(15, 23, 42, 0.6);
+}
+
+@media (prefers-color-scheme: dark) {
+  .empty {
+    color: rgba(226, 232, 240, 0.7);
+  }
+}
+
+.message {
+  padding: 1rem;
+  border-radius: 12px;
+  background-color: rgba(255, 255, 255, 0.95);
+  border: 1px solid rgba(15, 23, 42, 0.06);
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.message.user {
+  border-left: 4px solid rgba(37, 99, 235, 0.6);
+}
+
+.message.assistant {
+  border-left: 4px solid rgba(16, 185, 129, 0.55);
+}
+
+@media (prefers-color-scheme: dark) {
+  .message {
+    background-color: rgba(15, 23, 42, 0.74);
+    border-color: rgba(148, 163, 184, 0.12);
+  }
+
+  .message.user {
+    border-left-color: rgba(96, 165, 250, 0.6);
+  }
+
+  .message.assistant {
+    border-left-color: rgba(45, 212, 191, 0.6);
+  }
+}
+
+.message-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.role-label {
+  font-weight: 600;
+  letter-spacing: 0.01em;
+}
+
+.message-text {
+  margin: 0;
+  white-space: pre-wrap;
+  line-height: 1.55;
+}
+
+.tool-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.tool-card {
+  border-radius: 10px;
+  border: 1px solid rgba(37, 99, 235, 0.18);
+  padding: 0.75rem 0.85rem;
+  background: rgba(37, 99, 235, 0.07);
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.tool-card-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.tool-name {
+  font-weight: 600;
+}
+
+.tool-block {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.tool-block pre {
+  margin: 0;
+  padding: 0.6rem;
+  border-radius: 8px;
+  background: rgba(15, 23, 42, 0.08);
+  border: 1px solid rgba(15, 23, 42, 0.1);
+  font-size: 0.8rem;
+  line-height: 1.4;
+  max-height: 200px;
+  overflow: auto;
+  white-space: pre-wrap;
+}
+
+@media (prefers-color-scheme: dark) {
+  .tool-card {
+    background: rgba(96, 165, 250, 0.18);
+    border-color: rgba(96, 165, 250, 0.24);
+  }
+
+  .tool-block pre {
+    background: rgba(15, 23, 42, 0.78);
+    border-color: rgba(148, 163, 184, 0.2);
+  }
+}
+
+.hint {
+  margin: 0;
+  font-size: 0.8rem;
+  color: rgba(15, 23, 42, 0.6);
+}
+
+@media (prefers-color-scheme: dark) {
+  .hint {
+    color: rgba(226, 232, 240, 0.7);
+  }
+}
+
+.chat-form {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.actions {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: flex-end;
+  flex-wrap: wrap;
+}
diff --git a/examples/next-chat/app/layout.tsx b/examples/next-chat/app/layout.tsx
new file mode 100644
index 0000000..3c4e069
--- /dev/null
+++ b/examples/next-chat/app/layout.tsx
@@ -0,0 +1,17 @@
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: 'OpenRouter Chat Playground',
+  description:
+    'A minimal Next.js chat app that demonstrates streaming OpenRouter responses, model selection, and tool use.',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
diff --git a/examples/next-chat/app/page.tsx b/examples/next-chat/app/page.tsx
new file mode 100644
index 0000000..11cf687
--- /dev/null
+++ b/examples/next-chat/app/page.tsx
@@ -0,0 +1,566 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { FormEvent } from 'react';
+import type { ModelMessage } from 'ai';
+
+import type { ToolMode } from '../lib/models';
+import { DEFAULT_MODEL_ID, DEFAULT_TOOL_MODE, MODEL_OPTIONS } from '../lib/models';
+
+type ToolStatus = 'collecting' | 'running' | 'complete' | 'error';
+
+interface ToolCall {
+  id: string;
+  name: string;
+  status: ToolStatus;
+  inputText?: string;
+  resultText?: string;
+  errorText?: string;
+  providerExecuted?: boolean;
+}
+
+interface ConversationEntry {
+  id: string;
+  role: 'user' | 'assistant';
+  text: string;
+  tools: ToolCall[];
+  pending: boolean;
+}
+
+const TOOL_STATUS_LABEL: Record<ToolStatus, string> = {
+  collecting: 'Collecting input',
+  running: 'Running',
+  complete: 'Completed',
+  error: 'Error',
+};
+
+const TOOL_MODE_OPTIONS: Array<{ value: ToolMode; label: string }> = [
+  { value: 'auto', label: 'Automatic tool calling' },
+  { value: 'disabled', label: 'Disable tools' },
+];
+
+function createMessageId(counterRef: { current: number }, prefix: string) {
+  counterRef.current += 1;
+  return `${prefix}-${Date.now()}-${counterRef.current}`;
+}
+
+function mapConversationToModelMessages(history: ConversationEntry[]): ModelMessage[] {
+  return history.map((entry) =>
+    entry.role === 'user'
+      ? ({ role: 'user', content: entry.text } as ModelMessage)
+      : ({ role: 'assistant', content: entry.text } as ModelMessage),
+  );
+}
+
+function formatData(value: unknown): string {
+  if (value === undefined || value === null) {
+    return '—';
+  }
+
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+export default function ChatPage() {
+  const [conversation, setConversation] = useState<ConversationEntry[]>([]);
+  const [input, setInput] = useState('');
+  const [modelId, setModelId] = useState(DEFAULT_MODEL_ID);
+  const [toolMode, setToolMode] = useState<ToolMode>(DEFAULT_TOOL_MODE);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const messageCounterRef = useRef(0);
+  const currentAssistantIdRef = useRef<string | null>(null);
+
+  const selectedModel = useMemo(
+    () => MODEL_OPTIONS.find((option) => option.id === modelId) ?? MODEL_OPTIONS[0],
+    [modelId],
+  );
+  const toolsSupported = selectedModel?.supportsTools ?? false;
+
+  useEffect(() => {
+    if (!toolsSupported && toolMode !== 'disabled') {
+      setToolMode('disabled');
+    }
+  }, [toolMode, toolsSupported]);
+
+  const appendEntry = useCallback((entry: ConversationEntry) => {
+    setConversation((prev) => [...prev, entry]);
+  }, []);
+
+  const updateEntryById = useCallback(
+    (id: string, updater: (entry: ConversationEntry) => ConversationEntry) => {
+      setConversation((prev) => {
+        const index = prev.findIndex((item) => item.id === id);
+        if (index === -1) {
+          return prev;
+        }
+
+        const updated = updater(prev[index]);
+        if (updated === prev[index]) {
+          return prev;
+        }
+
+        const next = [...prev];
+        next[index] = updated;
+        return next;
+      });
+    },
+    [],
+  );
+
+  const handleStop = useCallback(() => {
+    abortControllerRef.current?.abort();
+  }, []);
+
+  const handleClear = useCallback(() => {
+    abortControllerRef.current?.abort();
+    abortControllerRef.current = null;
+    currentAssistantIdRef.current = null;
+    setConversation([]);
+    setInput('');
+    setError(null);
+    setIsStreaming(false);
+  }, []);
+
+  const streamResponse = useCallback(
+    async (history: ConversationEntry[]) => {
+      setIsStreaming(true);
+      const controller = new AbortController();
+      abortControllerRef.current = controller;
+
+      const payload = JSON.stringify({
+        messages: mapConversationToModelMessages(history),
+        modelId,
+        toolMode,
+      });
+
+      const toolBuffers = new Map<string, string>();
+
+      const ensureAssistantMessage = (messageId?: string) => {
+        if (currentAssistantIdRef.current) {
+          return currentAssistantIdRef.current;
+        }
+
+        const newId = messageId ?? createMessageId(messageCounterRef, 'assistant');
+        currentAssistantIdRef.current = newId;
+        appendEntry({
+          id: newId,
+          role: 'assistant',
+          text: '',
+          tools: [],
+          pending: true,
+        });
+        return newId;
+      };
+
+      const updateToolCall = (
+        assistantId: string,
+        toolId: string,
+        updater: (tool: ToolCall) => ToolCall,
+      ) => {
+        updateEntryById(assistantId, (entry) => ({
+          ...entry,
+          tools: entry.tools.map((tool) => (tool.id === toolId ? updater(tool) : tool)),
+        }));
+      };
+
+      const parseEvent = (eventText: string) => {
+        const dataLines = eventText
+          .split('\n')
+          .filter((line) => line.startsWith('data:'))
+          .map((line) => line.slice(5).trim());
+
+        if (dataLines.length === 0) {
+          return null;
+        }
+
+        const payloadText = dataLines.join('');
+        if (!payloadText) {
+          return null;
+        }
+
+        try {
+          return JSON.parse(payloadText) as Record<string, unknown>;
+        } catch {
+          return null;
+        }
+      };
+
+      const finalizeAssistant = (fallback?: string) => {
+        const assistantId = currentAssistantIdRef.current;
+        if (!assistantId) {
+          return;
+        }
+
+        updateEntryById(assistantId, (entry) => ({
+          ...entry,
+          text: entry.text || fallback || entry.text,
+          pending: false,
+        }));
+      };
+
+      const processChunk = (chunk: Record<string, unknown>) => {
+        const type = typeof chunk.type === 'string' ? chunk.type : null;
+        if (!type) {
+          return;
+        }
+
+        if (type === 'start') {
+          const messageId = typeof chunk.messageId === 'string' ? chunk.messageId : undefined;
+          ensureAssistantMessage(messageId);
+          return;
+        }
+
+        const assistantId = ensureAssistantMessage();
+
+        switch (type) {
+          case 'text-delta': {
+            if (typeof chunk.delta === 'string') {
+              updateEntryById(assistantId, (entry) => ({
+                ...entry,
+                text: entry.text + chunk.delta,
+              }));
+            }
+            break;
+          }
+          case 'tool-input-start': {
+            if (typeof chunk.toolCallId === 'string' && typeof chunk.toolName === 'string') {
+              toolBuffers.set(chunk.toolCallId, '');
+              const status: ToolStatus = chunk.providerExecuted === true ? 'running' : 'collecting';
+              updateEntryById(assistantId, (entry) => ({
+                ...entry,
+                tools: [
+                  ...entry.tools,
+                  {
+                    id: chunk.toolCallId as string,
+                    name: chunk.toolName as string,
+                    status,
+                    providerExecuted: chunk.providerExecuted === true,
+                  },
+                ],
+              }));
+            }
+            break;
+          }
+          case 'tool-input-delta': {
+            if (typeof chunk.toolCallId === 'string' && typeof chunk.inputTextDelta === 'string') {
+              const nextValue = (toolBuffers.get(chunk.toolCallId) ?? '') + chunk.inputTextDelta;
+              toolBuffers.set(chunk.toolCallId, nextValue);
+              updateToolCall(assistantId, chunk.toolCallId, (tool) => ({
+                ...tool,
+                inputText: nextValue,
+                status: tool.status === 'collecting' ? 'collecting' : tool.status,
+              }));
+            }
+            break;
+          }
+          case 'tool-input-available': {
+            if (typeof chunk.toolCallId === 'string') {
+              const formatted =
+                'input' in chunk ? formatData((chunk as { input?: unknown }).input) : undefined;
+              const preview = toolBuffers.get(chunk.toolCallId);
+              toolBuffers.delete(chunk.toolCallId);
+              updateToolCall(assistantId, chunk.toolCallId, (tool) => ({
+                ...tool,
+                inputText: formatted ?? preview ?? tool.inputText,
+                providerExecuted: tool.providerExecuted || chunk.providerExecuted === true,
+                status: 'running',
+              }));
+            }
+            break;
+          }
+          case 'tool-output-available': {
+            if (typeof chunk.toolCallId === 'string') {
+              const formatted =
+                'output' in chunk ? formatData((chunk as { output?: unknown }).output) : undefined;
+              updateToolCall(assistantId, chunk.toolCallId, (tool) => ({
+                ...tool,
+                resultText: formatted ?? tool.resultText,
+                status: 'complete',
+              }));
+            }
+            break;
+          }
+          case 'tool-output-error': {
+            if (typeof chunk.toolCallId === 'string') {
+              const errorText =
+                typeof chunk.errorText === 'string' ? chunk.errorText : 'Tool error';
+              updateToolCall(assistantId, chunk.toolCallId, (tool) => ({
+                ...tool,
+                errorText,
+                status: 'error',
+              }));
+            }
+            break;
+          }
+          case 'finish': {
+            updateEntryById(assistantId, (entry) => ({
+              ...entry,
+              pending: false,
+            }));
+            break;
+          }
+          case 'abort': {
+            finalizeAssistant('Response aborted.');
+            break;
+          }
+          case 'error': {
+            if (typeof chunk.errorText === 'string') {
+              setError(chunk.errorText);
+            }
+            finalizeAssistant('The model returned an error.');
+            break;
+          }
+          default:
+            break;
+        }
+      };
+
+      try {
+        const response = await fetch('/api/chat', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: payload,
+          signal: controller.signal,
+        });
+
+        if (!response.ok || !response.body) {
+          const message = await response.text();
+          throw new Error(message || 'Unable to reach the chat endpoint.');
+        }
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+
+        while (true) {
+          const { value, done } = await reader.read();
+          buffer += decoder.decode(value ?? new Uint8Array(), { stream: !done });
+
+          let boundary = buffer.indexOf('\n\n');
+          while (boundary !== -1) {
+            const eventText = buffer.slice(0, boundary);
+            buffer = buffer.slice(boundary + 2);
+            const chunk = parseEvent(eventText);
+            if (chunk) {
+              processChunk(chunk);
+            }
+            boundary = buffer.indexOf('\n\n');
+          }
+
+          if (done) {
+            break;
+          }
+        }
+
+        finalizeAssistant();
+      } catch (error) {
+        if (controller.signal.aborted) {
+          finalizeAssistant('Generation cancelled.');
+          return;
+        }
+
+        const message =
+          error instanceof Error ? error.message : 'Unexpected error while streaming response.';
+        setError(message);
+        finalizeAssistant('The response ended unexpectedly.');
+      } finally {
+        setIsStreaming(false);
+        abortControllerRef.current = null;
+        currentAssistantIdRef.current = null;
+      }
+    },
+    [appendEntry, modelId, toolMode, updateEntryById],
+  );
+
+  const handleSubmit = useCallback(
+    (event: FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      if (isStreaming) {
+        return;
+      }
+
+      const trimmed = input.trim();
+      if (!trimmed) {
+        return;
+      }
+
+      const userEntry: ConversationEntry = {
+        id: createMessageId(messageCounterRef, 'user'),
+        role: 'user',
+        text: trimmed,
+        tools: [],
+        pending: false,
+      };
+
+      const nextConversation = [...conversation, userEntry];
+      setConversation(nextConversation);
+      setInput('');
+      setError(null);
+      void streamResponse(nextConversation);
+    },
+    [conversation, input, isStreaming, streamResponse],
+  );
+
+  return (
+    <main>
+      <div className="container">
+        <header>
+          <h1>OpenRouter Chat Playground</h1>
+          <p className="subtitle">
+            Pick a model, decide whether tool calling is enabled, and chat with a streaming assistant.
+          </p>
+        </header>
+
+        <section className="controls">
+          <div className="control">
+            <label htmlFor="model-select">Model</label>
+            <select
+              id="model-select"
+              value={modelId}
+              onChange={(event) => setModelId(event.target.value)}
+              disabled={isStreaming}
+            >
+              {MODEL_OPTIONS.map((option) => (
+                <option key={option.id} value={option.id}>
+                  {option.label}
+                </option>
+              ))}
+            </select>
+            {selectedModel ? <p className="hint">{selectedModel.description}</p> : null}
+          </div>
+
+          <div className="control">
+            <label htmlFor="tool-mode">Tool usage</label>
+            <select
+              id="tool-mode"
+              value={toolMode}
+              onChange={(event) => setToolMode(event.target.value as ToolMode)}
+              disabled={!toolsSupported || isStreaming}
+            >
+              {TOOL_MODE_OPTIONS.map((option) => (
+                <option
+                  key={option.value}
+                  value={option.value}
+                  disabled={option.value === 'auto' && !toolsSupported}
+                >
+                  {option.label}
+                </option>
+              ))}
+            </select>
+            {!toolsSupported ? <p className="hint">Tools are disabled for this model.</p> : null}
+          </div>
+
+          <div className="control">
+            <span className="label">Status</span>
+            <span className={`badge ${isStreaming ? 'active' : 'idle'}`}>
+              {isStreaming ? 'Streaming response…' : 'Ready'}
+            </span>
+          </div>
+
+          <div className="control">
+            <span className="label">Conversation</span>
+            <button
+              type="button"
+              className="secondary"
+              onClick={handleClear}
+              disabled={conversation.length === 0 && !isStreaming}
+            >
+              Clear conversation
+            </button>
+          </div>
+        </section>
+
+        <section className="chat-panel">
+          {error ? <div className="alert">{error}</div> : null}
+          <div className="chat-log">
+            {conversation.length === 0 ? (
+              <p className="empty">
+                Start by asking a question. The assistant streams its reply and displays each tool call.
+              </p>
+            ) : (
+              conversation.map((entry) => (
+                <article key={entry.id} className={`message ${entry.role}`}>
+                  <header className="message-header">
+                    <span className="role-label">{entry.role === 'user' ? 'You' : 'Assistant'}</span>
+                    {entry.pending ? <span className="badge active">Streaming…</span> : null}
+                  </header>
+                  {entry.text ? <p className="message-text">{entry.text}</p> : null}
+                  {entry.tools.length > 0 ? (
+                    <div className="tool-list">
+                      {entry.tools.map((tool) => (
+                        <div key={tool.id} className="tool-card">
+                          <div className="tool-card-header">
+                            <span className="tool-name">{tool.name}</span>
+                            <span className={`badge status ${tool.status}`}>
+                              {TOOL_STATUS_LABEL[tool.status]}
+                            </span>
+                          </div>
+                          {tool.providerExecuted ? <p className="hint">Executed by provider</p> : null}
+                          {tool.inputText ? (
+                            <div className="tool-block">
+                              <p className="label">Input</p>
+                              <pre>{tool.inputText}</pre>
+                            </div>
+                          ) : null}
+                          {tool.resultText ? (
+                            <div className="tool-block">
+                              <p className="label">Result</p>
+                              <pre>{tool.resultText}</pre>
+                            </div>
+                          ) : null}
+                          {tool.errorText ? (
+                            <div className="tool-block">
+                              <p className="label">Error</p>
+                              <pre>{tool.errorText}</pre>
+                            </div>
+                          ) : null}
+                        </div>
+                      ))}
+                    </div>
+                  ) : null}
+                </article>
+              ))
+            )}
+          </div>
+
+          <form className="chat-form" onSubmit={handleSubmit}>
+            <label htmlFor="user-input" className="label">
+              Your message
+            </label>
+            <textarea
+              id="user-input"
+              placeholder="Ask anything — try planning a trip or requesting structured data."
+              value={input}
+              onChange={(event) => setInput(event.target.value)}
+              disabled={isStreaming}
+              rows={3}
+            />
+            <div className="actions">
+              <button
+                type="button"
+                className="secondary"
+                onClick={handleStop}
+                disabled={!isStreaming}
+              >
+                Stop streaming
+              </button>
+              <button type="submit" className="primary" disabled={isStreaming}>
+                Send message
+              </button>
+            </div>
+          </form>
+        </section>
+      </div>
+    </main>
+  );
+}
diff --git a/examples/next-chat/lib/models.ts b/examples/next-chat/lib/models.ts
new file mode 100644
index 0000000..ab244e0
--- /dev/null
+++ b/examples/next-chat/lib/models.ts
@@ -0,0 +1,71 @@
+/**
+ * Represents a model option in the UI.
+ */
+export interface ModelOption {
+  /**
+   * The ID of the model.
+   */
+  id: string;
+  /**
+   * The label for the model.
+   */
+  label: string;
+  /**
+   * A description of the model.
+   */
+  description: string;
+  /**
+   * Whether the model supports tools.
+   */
+  supportsTools: boolean;
+}
+
+/**
+ * The mode for using tools.
+ */
+export type ToolMode = 'auto' | 'disabled';
+
+/**
+ * The available model options.
+ */
+export const MODEL_OPTIONS: ModelOption[] = [
+  {
+    id: 'openai/gpt-4.1-mini',
+    label: 'OpenAI GPT-4.1 Mini',
+    description:
+      'Fast and capable general-purpose model with strong support for streaming tool calls.',
+    supportsTools: true,
+  },
+  {
+    id: 'anthropic/claude-3.7-sonnet',
+    label: 'Anthropic Claude 3.7 Sonnet',
+    description:
+      'Reasoning-focused assistant that can plan multi-step solutions and execute structured tools.',
+    supportsTools: true,
+  },
+  {
+    id: 'meta-llama/llama-3.1-70b-instruct',
+    label: 'Llama 3.1 70B Instruct',
+    description:
+      'Great open-weight model for narrative tasks. Tools are disabled by default for this model.',
+    supportsTools: false,
+  },
+];
+
+/**
+ * The default model ID.
+ */
+export const DEFAULT_MODEL_ID = MODEL_OPTIONS[0]?.id ?? 'openai/gpt-4.1-mini';
+
+/**
+ * The default tool mode.
+ */
+export const DEFAULT_TOOL_MODE: ToolMode = 'auto';
+
+/**
+ * The default system prompt.
+ */
+export const DEFAULT_SYSTEM_PROMPT =
+  'You are an expert assistant running on OpenRouter. Provide concise, actionable answers, '
+  + 'call the available tools when they make the response more helpful, and always explain how '
+  + 'you used any tool results.';
diff --git a/examples/next-chat/lib/tools.ts b/examples/next-chat/lib/tools.ts
new file mode 100644
index 0000000..98a8d34
--- /dev/null
+++ b/examples/next-chat/lib/tools.ts
@@ -0,0 +1,91 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+
+function roundTo(value: number, decimals: number) {
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+
+/**
+ * A tool for getting the current weather.
+ */
+export const getCurrentWeather = tool({
+  description:
+    'Look up an approximate weather report for a location. Useful for travel planning or casual questions.',
+  inputSchema: z.object({
+    location: z
+      .string({ description: 'City, region, or coordinates describing the location to inspect.' })
+      .min(2),
+    unit: z
+      .enum(['celsius', 'fahrenheit'], {
+        description: 'Unit to use when reporting the temperature.',
+      })
+      .default('celsius'),
+  }),
+  execute: async ({ location, unit }) => {
+    const fakeTemperatureCelsius = 18 + Math.random() * 10;
+    const temperatureCelsius = roundTo(fakeTemperatureCelsius, 1);
+    const temperatureFahrenheit = roundTo((temperatureCelsius * 9) / 5 + 32, 1);
+
+    return {
+      location,
+      unit,
+      report: `Skies are mostly clear over ${location}. A gentle breeze keeps the humidity comfortable.`,
+      temperature: unit === 'celsius' ? temperatureCelsius : temperatureFahrenheit,
+      feelsLike: unit === 'celsius'
+        ? roundTo(temperatureCelsius - 1.1, 1)
+        : roundTo(temperatureFahrenheit - 1.8, 1),
+      humidity: roundTo(52 + Math.random() * 8, 1),
+      windKph: roundTo(8 + Math.random() * 6, 1),
+      source: 'open-meteorology.example',
+    };
+  },
+});
+
+/**
+ * A tool for getting the current time.
+ */
+export const getCurrentTime = tool({
+  description:
+    'Return the current local time for a requested IANA timezone or city description. '
+    + 'Helpful for scheduling and calendar coordination tasks.',
+  inputSchema: z.object({
+    timezone: z
+      .string({ description: 'An IANA timezone such as "Europe/Paris" or "America/New_York".' })
+      .default('UTC'),
+    locale: z
+      .string({ description: 'BCP47 locale string used when formatting the timestamp.' })
+      .default('en-US'),
+  }),
+  execute: async ({ timezone, locale }) => {
+    const now = new Date();
+    let formatted: string;
+    try {
+      formatted = now.toLocaleString(locale, { timeZone: timezone, hour12: false });
+    } catch (_error) {
+      formatted = now.toLocaleString('en-US', { timeZone: 'UTC', hour12: false });
+      return {
+        timezone,
+        locale,
+        iso: now.toISOString(),
+        formatted,
+        note: `Unable to format for timezone "${timezone}". Falling back to UTC.`,
+      };
+    }
+
+    return {
+      timezone,
+      locale,
+      iso: now.toISOString(),
+      formatted,
+    };
+  },
+});
+
+/**
+ * A set of basic tools that can be used by the assistant.
+ */
+export const BASIC_TOOLS = {
+  getCurrentWeather,
+  getCurrentTime,
+};
diff --git a/examples/next-chat/next-env.d.ts b/examples/next-chat/next-env.d.ts
new file mode 100644
index 0000000..4f11a03
--- /dev/null
+++ b/examples/next-chat/next-env.d.ts
@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.
diff --git a/examples/next-chat/next.config.mjs b/examples/next-chat/next.config.mjs
new file mode 100644
index 0000000..d5456a1
--- /dev/null
+++ b/examples/next-chat/next.config.mjs
@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+};
+
+export default nextConfig;
diff --git a/examples/next-chat/package.json b/examples/next-chat/package.json
new file mode 100644
index 0000000..9af84ae
--- /dev/null
+++ b/examples/next-chat/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "@openrouter/examples-next-chat",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@openrouter/ai-sdk-provider": "workspace:*",
+    "ai": "5.0.5",
+    "next": "14.2.15",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "20.17.24",
+    "@types/react": "18.3.5",
+    "@types/react-dom": "18.3.0",
+    "typescript": "5.9.2"
+  }
+}
diff --git a/examples/next-chat/tsconfig.json b/examples/next-chat/tsconfig.json
new file mode 100644
index 0000000..81bf283
--- /dev/null
+++ b/examples/next-chat/tsconfig.json
@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "types": ["node"]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index bd8ded7..3759f2c 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,5 +1,6 @@
 packages:
   - '.'
+  - 'examples/*'
 
 onlyBuiltDependencies:
   - '@biomejs/biome'
diff --git a/src/chat/convert-to-openrouter-chat-messages.ts b/src/chat/convert-to-openrouter-chat-messages.ts
index 3f033f1..18fe50e 100644
--- a/src/chat/convert-to-openrouter-chat-messages.ts
+++ b/src/chat/convert-to-openrouter-chat-messages.ts
@@ -15,7 +15,10 @@ import { ReasoningDetailType } from '@/src/schemas/reasoning-details';
 import { getFileUrl } from './file-url-utils';
 import { isUrl } from './is-url';
 
-// Type for OpenRouter Cache Control following Anthropic's pattern
+/**
+ * Type for OpenRouter Cache Control, following Anthropic's pattern.
+ * It is used to control caching behavior for requests.
+ */
 export type OpenRouterCacheControl = { type: 'ephemeral' };
 
 function getCacheControl(
@@ -31,6 +34,12 @@ function getCacheControl(
     anthropic?.cache_control) as OpenRouterCacheControl | undefined;
 }
 
+/**
+ * Converts a prompt from the AI SDK V2 format to the OpenRouter Chat Completions format.
+ *
+ * @param {LanguageModelV2Prompt} prompt - The prompt to convert.
+ * @returns {OpenRouterChatCompletionsInput} The converted prompt in OpenRouter format.
+ */
 export function convertToOpenRouterChatMessages(
   prompt: LanguageModelV2Prompt,
 ): OpenRouterChatCompletionsInput {
diff --git a/src/chat/file-url-utils.ts b/src/chat/file-url-utils.ts
index 700b246..e990fed 100644
--- a/src/chat/file-url-utils.ts
+++ b/src/chat/file-url-utils.ts
@@ -3,6 +3,14 @@ import type { LanguageModelV2FilePart } from '@ai-sdk/provider';
 import { convertUint8ArrayToBase64 } from '@ai-sdk/provider-utils';
 import { isUrl } from './is-url';
 
+/**
+ * Gets a URL for a file part, converting it to a data URL if necessary.
+ *
+ * @param {object} options - The options for getting the file URL.
+ * @param {LanguageModelV2FilePart} options.part - The file part to get the URL for.
+ * @param {string} options.defaultMediaType - The default media type to use if the part doesn't have one.
+ * @returns {string} The URL for the file part.
+ */
 export function getFileUrl({
   part,
   defaultMediaType,
@@ -31,11 +39,24 @@ export function getFileUrl({
     : `data:${part.mediaType ?? defaultMediaType};base64,${stringUrl}`;
 }
 
+/**
+ * Gets the media type from a data URL.
+ *
+ * @param {string} dataUrl - The data URL to get the media type from.
+ * @param {string} defaultMediaType - The default media type to use if it can't be determined from the URL.
+ * @returns {string} The media type of the data URL.
+ */
 export function getMediaType(dataUrl: string, defaultMediaType: string): string {
   const match = dataUrl.match(/^data:([^;]+)/);
   return match ? match[1] ?? defaultMediaType : defaultMediaType;
 }
 
+/**
+ * Gets the base64 content from a data URL.
+ *
+ * @param {string} dataUrl - The data URL to get the base64 content from.
+ * @returns {string} The base64 content of the data URL.
+ */
 export function getBase64FromDataUrl(dataUrl: string): string {
   const match = dataUrl.match(/^data:[^;]*;base64,(.+)$/);
   return match ? match[1]! : dataUrl;
diff --git a/src/chat/get-tool-choice.ts b/src/chat/get-tool-choice.ts
index f7370a7..13a10c3 100644
--- a/src/chat/get-tool-choice.ts
+++ b/src/chat/get-tool-choice.ts
@@ -16,6 +16,13 @@ const ChatCompletionToolChoiceSchema = z.union([
 
 type ChatCompletionToolChoice = z.infer<typeof ChatCompletionToolChoiceSchema>;
 
+/**
+ * Gets the chat completion tool choice from the language model tool choice.
+ *
+ * @param {LanguageModelV2ToolChoice} toolChoice - The language model tool choice to convert.
+ * @returns {ChatCompletionToolChoice} The chat completion tool choice.
+ * @throws {Error} If the tool choice type is invalid.
+ */
 export function getChatCompletionToolChoice(
   toolChoice: LanguageModelV2ToolChoice,
 ): ChatCompletionToolChoice {
diff --git a/src/chat/index.ts b/src/chat/index.ts
index f4d4cec..8c9e6ed 100644
--- a/src/chat/index.ts
+++ b/src/chat/index.ts
@@ -47,6 +47,13 @@ type OpenRouterChatConfig = {
   extraBody?: Record<string, unknown>;
 };
 
+/**
+ * A concrete implementation of a language model that interacts with the OpenRouter API.
+ * This class is responsible for making API calls to OpenRouter for chat completions.
+ * It handles both streaming and non-streaming responses.
+ *
+ * @implements {LanguageModelV2}
+ */
 export class OpenRouterChatLanguageModel implements LanguageModelV2 {
   readonly specificationVersion = 'v2' as const;
   readonly provider = 'openrouter';
@@ -185,6 +192,14 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
     return baseArgs;
   }
 
+  /**
+   * Performs a non-streaming generation task.
+   * It sends a request to the OpenRouter API and returns the result as a promise.
+   *
+   * @param {LanguageModelV2CallOptions} options - The options for the language model call.
+   * @returns {Promise<object>} A promise that resolves to an object containing the content, finish reason, usage, and other metadata.
+   * @throws {Error} If the response from the API is invalid or does not contain a choice.
+   */
   async doGenerate(options: LanguageModelV2CallOptions): Promise<{
     content: Array<LanguageModelV2Content>;
     finishReason: LanguageModelV2FinishReason;
@@ -393,6 +408,13 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
     };
   }
 
+  /**
+   * Performs a streaming generation task.
+   * It sends a request to the OpenRouter API and returns a readable stream of the response.
+   *
+   * @param {LanguageModelV2CallOptions} options - The options for the language model call.
+   * @returns {Promise<object>} A promise that resolves to an object containing the stream, warnings, and other metadata.
+   */
   async doStream(options: LanguageModelV2CallOptions): Promise<{
     stream: ReadableStream<LanguageModelV2StreamPart>;
     warnings: Array<LanguageModelV2CallWarning>;
diff --git a/src/chat/is-url.ts b/src/chat/is-url.ts
index 3de7f0f..e58ce4a 100644
--- a/src/chat/is-url.ts
+++ b/src/chat/is-url.ts
@@ -1,3 +1,11 @@
+/**
+ * Checks if a given string is a URL with a valid protocol.
+ *
+ * @param {object} options - The options for checking the URL.
+ * @param {string | URL} options.url - The URL to check.
+ * @param {Set<`${string}:`>} options.protocols - A set of allowed protocols.
+ * @returns {boolean} True if the URL is valid and has an allowed protocol, false otherwise.
+ */
 export function isUrl({
   url,
   protocols,
diff --git a/src/chat/schemas.ts b/src/chat/schemas.ts
index 4eb730c..bb7553f 100644
--- a/src/chat/schemas.ts
+++ b/src/chat/schemas.ts
@@ -31,8 +31,11 @@ const OpenRouterChatCompletionBaseResponseSchema = z.object({
     })
     .nullish(),
 });
-// limited version of the schema, focussed on what is needed for the implementation
-// this approach limits breakages when the API changes and increases efficiency
+/**
+ * Zod schema for the response of a non-streaming OpenRouter chat completion.
+ * It is a limited version of the schema, focussed on what is needed for the implementation.
+ * This approach limits breakages when the API changes and increases efficiency.
+ */
 export const OpenRouterNonStreamChatCompletionResponseSchema =
   OpenRouterChatCompletionBaseResponseSchema.extend({
     choices: z.array(
@@ -96,8 +99,11 @@ export const OpenRouterNonStreamChatCompletionResponseSchema =
       }),
     ),
   });
-// limited version of the schema, focussed on what is needed for the implementation
-// this approach limits breakages when the API changes and increases efficiency
+/**
+ * Zod schema for a chunk of a streaming OpenRouter chat completion.
+ * It is a limited version of the schema, focussed on what is needed for the implementation.
+ * This approach limits breakages when the API changes and increases efficiency.
+ */
 export const OpenRouterStreamChatCompletionChunkSchema = z.union([
   OpenRouterChatCompletionBaseResponseSchema.extend({
     choices: z.array(
diff --git a/src/completion/convert-to-openrouter-completion-prompt.ts b/src/completion/convert-to-openrouter-completion-prompt.ts
index 9435d88..4e022ae 100644
--- a/src/completion/convert-to-openrouter-completion-prompt.ts
+++ b/src/completion/convert-to-openrouter-completion-prompt.ts
@@ -12,6 +12,18 @@ import {
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
 
+/**
+ * Converts a language model prompt to the OpenRouter completion prompt format.
+ *
+ * @param {object} options - The options for the conversion.
+ * @param {LanguageModelV2Prompt} options.prompt - The prompt to convert.
+ * @param {'prompt' | 'messages'} options.inputFormat - The input format of the prompt.
+ * @param {string} [options.user='user'] - The user role label.
+ * @param {string} [options.assistant='assistant'] - The assistant role label.
+ * @returns {{ prompt: string }} The converted prompt.
+ * @throws {InvalidPromptError} If the prompt is invalid.
+ * @throws {UnsupportedFunctionalityError} If the prompt contains unsupported functionality.
+ */
 export function convertToOpenRouterCompletionPrompt({
   prompt,
   inputFormat,
diff --git a/src/completion/index.ts b/src/completion/index.ts
index d2d1523..dcfc9b8 100644
--- a/src/completion/index.ts
+++ b/src/completion/index.ts
@@ -35,6 +35,13 @@ type OpenRouterCompletionConfig = {
   extraBody?: Record<string, unknown>;
 };
 
+/**
+ * A concrete implementation of a language model that interacts with the OpenRouter API for completions.
+ * This class is responsible for making API calls to OpenRouter for text completions.
+ * It handles both streaming and non-streaming responses.
+ *
+ * @implements {LanguageModelV2}
+ */
 export class OpenRouterCompletionLanguageModel implements LanguageModelV2 {
   readonly specificationVersion = 'v2' as const;
   readonly provider = 'openrouter';
@@ -136,6 +143,14 @@ export class OpenRouterCompletionLanguageModel implements LanguageModelV2 {
     };
   }
 
+  /**
+   * Performs a non-streaming generation task.
+   * It sends a request to the OpenRouter API and returns the result as a promise.
+   *
+   * @param {LanguageModelV2CallOptions} options - The options for the language model call.
+   * @returns {Promise<object>} A promise that resolves to an object containing the content, finish reason, usage, and other metadata.
+   * @throws {Error} If the response from the API is invalid or does not contain a choice.
+   */
   async doGenerate(
     options: LanguageModelV2CallOptions,
   ): Promise<Awaited<ReturnType<LanguageModelV2['doGenerate']>>> {
@@ -198,6 +213,13 @@ export class OpenRouterCompletionLanguageModel implements LanguageModelV2 {
     };
   }
 
+  /**
+   * Performs a streaming generation task.
+   * It sends a request to the OpenRouter API and returns a readable stream of the response.
+   *
+   * @param {LanguageModelV2CallOptions} options - The options for the language model call.
+   * @returns {Promise<object>} A promise that resolves to an object containing the stream, warnings, and other metadata.
+   */
   async doStream(
     options: LanguageModelV2CallOptions,
   ): Promise<Awaited<ReturnType<LanguageModelV2['doStream']>>> {
diff --git a/src/completion/schemas.ts b/src/completion/schemas.ts
index 2875879..def73d9 100644
--- a/src/completion/schemas.ts
+++ b/src/completion/schemas.ts
@@ -2,8 +2,11 @@ import { z } from 'zod/v4';
 import { OpenRouterErrorResponseSchema } from '../schemas/error-response';
 import { ReasoningDetailArraySchema } from '../schemas/reasoning-details';
 
-// limited version of the schema, focussed on what is needed for the implementation
-// this approach limits breakages when the API changes and increases efficiency
+/**
+ * Zod schema for a chunk of an OpenRouter completion.
+ * It is a limited version of the schema, focussed on what is needed for the implementation.
+ * This approach limits breakages when the API changes and increases efficiency.
+ */
 export const OpenRouterCompletionChunkSchema = z.union([
   z.object({
     id: z.string().optional(),
diff --git a/src/facade.ts b/src/facade.ts
index 1440058..50bcd99 100644
--- a/src/facade.ts
+++ b/src/facade.ts
@@ -58,6 +58,13 @@ Custom headers to include in the requests.
     };
   }
 
+  /**
+   * Creates a new chat model.
+   *
+   * @param {OpenRouterChatModelId} modelId - The ID of the chat model to use.
+   * @param {OpenRouterChatSettings} [settings={}] - The settings for the chat model.
+   * @returns {OpenRouterChatLanguageModel} A new chat model instance.
+   */
   chat(modelId: OpenRouterChatModelId, settings: OpenRouterChatSettings = {}) {
     return new OpenRouterChatLanguageModel(modelId, settings, {
       provider: 'openrouter.chat',
@@ -67,6 +74,13 @@ Custom headers to include in the requests.
     });
   }
 
+  /**
+   * Creates a new completion model.
+   *
+   * @param {OpenRouterCompletionModelId} modelId - The ID of the completion model to use.
+   * @param {OpenRouterCompletionSettings} [settings={}] - The settings for the completion model.
+   * @returns {OpenRouterCompletionLanguageModel} A new completion model instance.
+   */
   completion(
     modelId: OpenRouterCompletionModelId,
     settings: OpenRouterCompletionSettings = {},
diff --git a/src/provider.ts b/src/provider.ts
index e0c4000..5a736df 100644
--- a/src/provider.ts
+++ b/src/provider.ts
@@ -14,27 +14,62 @@ import { OpenRouterCompletionLanguageModel } from './completion';
 
 export type { OpenRouterCompletionSettings };
 
+/**
+ * A provider for the OpenRouter API.
+ */
 export interface OpenRouterProvider extends LanguageModelV2 {
+  /**
+   * Creates a new OpenRouter language model.
+   *
+   * @param {OpenRouterChatModelId} modelId - The ID of the model to use.
+   * @param {OpenRouterCompletionSettings} [settings] - The settings for the model.
+   * @returns {OpenRouterCompletionLanguageModel} A new completion model instance.
+   */
   (
     modelId: OpenRouterChatModelId,
     settings?: OpenRouterCompletionSettings,
   ): OpenRouterCompletionLanguageModel;
+  /**
+   * Creates a new OpenRouter language model.
+   *
+   * @param {OpenRouterChatModelId} modelId - The ID of the model to use.
+   * @param {OpenRouterChatSettings} [settings] - The settings for the model.
+   * @returns {OpenRouterChatLanguageModel} A new chat model instance.
+   */
   (
     modelId: OpenRouterChatModelId,
     settings?: OpenRouterChatSettings,
   ): OpenRouterChatLanguageModel;
 
+  /**
+   * Creates a new OpenRouter language model.
+   *
+   * @param {OpenRouterChatModelId} modelId - The ID of the model to use.
+   * @param {OpenRouterCompletionSettings} [settings] - The settings for the model.
+   * @returns {OpenRouterCompletionLanguageModel} A new completion model instance.
+   */
   languageModel(
     modelId: OpenRouterChatModelId,
     settings?: OpenRouterCompletionSettings,
   ): OpenRouterCompletionLanguageModel;
+  /**
+   * Creates a new OpenRouter language model.
+   *
+   * @param {OpenRouterChatModelId} modelId - The ID of the model to use.
+   * @param {OpenRouterChatSettings} [settings] - The settings for the model.
+   * @returns {OpenRouterChatLanguageModel} A new chat model instance.
+   */
   languageModel(
     modelId: OpenRouterChatModelId,
     settings?: OpenRouterChatSettings,
   ): OpenRouterChatLanguageModel;
 
   /**
-Creates an OpenRouter chat model for text generation.
+   * Creates an OpenRouter chat model for text generation.
+   *
+   * @param {OpenRouterChatModelId} modelId - The ID of the chat model to use.
+   * @param {OpenRouterChatSettings} [settings] - The settings for the chat model.
+   * @returns {OpenRouterChatLanguageModel} A new chat model instance.
    */
   chat(
     modelId: OpenRouterChatModelId,
@@ -42,7 +77,11 @@ Creates an OpenRouter chat model for text generation.
   ): OpenRouterChatLanguageModel;
 
   /**
-Creates an OpenRouter completion model for text generation.
+   * Creates an OpenRouter completion model for text generation.
+   *
+   * @param {OpenRouterCompletionModelId} modelId - The ID of the completion model to use.
+   * @param {OpenRouterCompletionSettings} [settings] - The settings for the completion model.
+   * @returns {OpenRouterCompletionLanguageModel} A new completion model instance.
    */
   completion(
     modelId: OpenRouterCompletionModelId,
@@ -50,43 +89,46 @@ Creates an OpenRouter completion model for text generation.
   ): OpenRouterCompletionLanguageModel;
 }
 
+/**
+ * Settings for the OpenRouter provider.
+ */
 export interface OpenRouterProviderSettings {
   /**
-Base URL for the OpenRouter API calls.
-     */
+   * Base URL for the OpenRouter API calls.
+   */
   baseURL?: string;
 
   /**
-@deprecated Use `baseURL` instead.
-     */
+   * @deprecated Use `baseURL` instead.
+   */
   baseUrl?: string;
 
   /**
-API key for authenticating requests.
-     */
+   * API key for authenticating requests.
+   */
   apiKey?: string;
 
   /**
-Custom headers to include in the requests.
-     */
+   * Custom headers to include in the requests.
+   */
   headers?: Record<string, string>;
 
   /**
-OpenRouter compatibility mode. Should be set to `strict` when using the OpenRouter API,
-and `compatible` when using 3rd party providers. In `compatible` mode, newer
-information such as streamOptions are not being sent. Defaults to 'compatible'.
+   * OpenRouter compatibility mode. Should be set to `strict` when using the OpenRouter API,
+   * and `compatible` when using 3rd party providers. In `compatible` mode, newer
+   * information such as streamOptions are not being sent. Defaults to 'compatible'.
    */
   compatibility?: 'strict' | 'compatible';
 
   /**
-Custom fetch implementation. You can use it as a middleware to intercept requests,
-or to provide a custom fetch implementation for e.g. testing.
-    */
+   * Custom fetch implementation. You can use it as a middleware to intercept requests,
+   * or to provide a custom fetch implementation for e.g. testing.
+   */
   fetch?: typeof fetch;
 
   /**
-A JSON object to send as the request body to access OpenRouter features & upstream provider features.
-  */
+   * A JSON object to send as the request body to access OpenRouter features & upstream provider features.
+   */
   extraBody?: Record<string, unknown>;
 }
 
diff --git a/src/schemas/error-response.ts b/src/schemas/error-response.ts
index d984a82..1c7d785 100644
--- a/src/schemas/error-response.ts
+++ b/src/schemas/error-response.ts
@@ -1,6 +1,9 @@
 import { createJsonErrorResponseHandler } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
+/**
+ * Zod schema for the error response from the OpenRouter API.
+ */
 export const OpenRouterErrorResponseSchema = z.object({
   error: z.object({
     code: z.union([z.string(), z.number()]).nullable().optional().default(null),
@@ -10,8 +13,16 @@ export const OpenRouterErrorResponseSchema = z.object({
   }),
 });
 
+/**
+ * Type for the error data from the OpenRouter API.
+ */
 export type OpenRouterErrorData = z.infer<typeof OpenRouterErrorResponseSchema>;
 
+/**
+ * A failed response handler for the OpenRouter API.
+ * It uses the `OpenRouterErrorResponseSchema` to parse the error response
+ * and extracts the error message.
+ */
 export const openrouterFailedResponseHandler = createJsonErrorResponseHandler({
   errorSchema: OpenRouterErrorResponseSchema,
   errorToMessage: (data: OpenRouterErrorData) => data.error.message,
diff --git a/src/schemas/image.ts b/src/schemas/image.ts
index bb08cf8..62b123f 100644
--- a/src/schemas/image.ts
+++ b/src/schemas/image.ts
@@ -7,6 +7,9 @@ const ImageResponseSchema = z.object({
   }),
 });
 
+/**
+ * Type for an image response from the OpenRouter API.
+ */
 export type ImageResponse = z.infer<typeof ImageResponseSchema>;
 
 const ImageResponseWithUnknownSchema = z.union([
@@ -14,6 +17,10 @@ const ImageResponseWithUnknownSchema = z.union([
   z.unknown().transform(() => null),
 ]);
 
+/**
+ * Zod schema for an array of image responses from the OpenRouter API.
+ * It filters out any unknown or invalid entries in the array.
+ */
 export const ImageResponseArraySchema = z
   .array(ImageResponseWithUnknownSchema)
   .transform((d) => d.filter((d): d is ImageResponse => !!d));
diff --git a/src/schemas/reasoning-details.ts b/src/schemas/reasoning-details.ts
index 9550257..63b8ba0 100644
--- a/src/schemas/reasoning-details.ts
+++ b/src/schemas/reasoning-details.ts
@@ -1,35 +1,61 @@
 import { z } from 'zod/v4';
 
+/**
+ * Enum for the different types of reasoning details.
+ */
 export enum ReasoningDetailType {
   Summary = 'reasoning.summary',
   Encrypted = 'reasoning.encrypted',
   Text = 'reasoning.text',
 }
 
+/**
+ * Zod schema for a summary reasoning detail.
+ */
 export const ReasoningDetailSummarySchema = z.object({
   type: z.literal(ReasoningDetailType.Summary),
   summary: z.string(),
 });
+
+/**
+ * Type for a summary reasoning detail.
+ */
 export type ReasoningDetailSummary = z.infer<
   typeof ReasoningDetailSummarySchema
 >;
 
+/**
+ * Zod schema for an encrypted reasoning detail.
+ */
 export const ReasoningDetailEncryptedSchema = z.object({
   type: z.literal(ReasoningDetailType.Encrypted),
   data: z.string(),
 });
+
+/**
+ * Type for an encrypted reasoning detail.
+ */
 export type ReasoningDetailEncrypted = z.infer<
   typeof ReasoningDetailEncryptedSchema
 >;
 
+/**
+ * Zod schema for a text reasoning detail.
+ */
 export const ReasoningDetailTextSchema = z.object({
   type: z.literal(ReasoningDetailType.Text),
   text: z.string().nullish(),
   signature: z.string().nullish(),
 });
 
+/**
+ * Type for a text reasoning detail.
+ */
 export type ReasoningDetailText = z.infer<typeof ReasoningDetailTextSchema>;
 
+/**
+ * Zod schema for a union of all reasoning detail types.
+ */
 export const ReasoningDetailUnionSchema = z.union([
   ReasoningDetailSummarySchema,
   ReasoningDetailEncryptedSchema,
@@ -41,8 +67,15 @@ const ReasoningDetailsWithUnknownSchema = z.union([
   z.unknown().transform(() => null),
 ]);
 
+/**
+ * Type for a union of all reasoning detail types.
+ */
 export type ReasoningDetailUnion = z.infer<typeof ReasoningDetailUnionSchema>;
 
+/**
+ * Zod schema for an array of reasoning details.
+ * It filters out any unknown or invalid entries in the array.
+ */
 export const ReasoningDetailArraySchema = z
   .array(ReasoningDetailsWithUnknownSchema)
   .transform((d) => d.filter((d): d is ReasoningDetailUnion => !!d));
diff --git a/src/types/index.ts b/src/types/index.ts
index 19e7152..6347e8a 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -2,22 +2,39 @@ import type { LanguageModelV2, LanguageModelV2Prompt } from '@ai-sdk/provider';
 
 export type { LanguageModelV2, LanguageModelV2Prompt };
 
+/**
+ * Options for the OpenRouter provider.
+ */
 export type OpenRouterProviderOptions = {
+  /**
+   * A list of models to use for the request.
+   */
   models?: string[];
 
   /**
-   * https://openrouter.ai/docs/use-cases/reasoning-tokens
-   * One of `max_tokens` or `effort` is required.
-   * If `exclude` is true, reasoning will be removed from the response. Default is false.
+   * Options for reasoning tokens.
+   * @see https://openrouter.ai/docs/use-cases/reasoning-tokens
    */
   reasoning?: {
+    /**
+     * Whether to enable reasoning.
+     */
     enabled?: boolean;
+    /**
+     * Whether to exclude reasoning from the response.
+     */
     exclude?: boolean;
   } & (
     | {
+        /**
+         * The maximum number of tokens to use for reasoning.
+         */
         max_tokens: number;
       }
     | {
+        /**
+         * The effort level for reasoning.
+         */
         effort: 'high' | 'medium' | 'low';
       }
   );
@@ -29,17 +46,23 @@ export type OpenRouterProviderOptions = {
   user?: string;
 };
 
+/**
+ * Shared settings for the OpenRouter provider.
+ */
 export type OpenRouterSharedSettings = OpenRouterProviderOptions & {
   /**
    * @deprecated use `reasoning` instead
    */
   includeReasoning?: boolean;
 
+  /**
+   * Extra body parameters to send to the API.
+   */
   extraBody?: Record<string, unknown>;
 
   /**
    * Enable usage accounting to get detailed token usage information.
-   * https://openrouter.ai/docs/use-cases/usage-accounting
+   * @see https://openrouter.ai/docs/use-cases/usage-accounting
    */
   usage?: {
     /**
@@ -50,21 +73,51 @@ export type OpenRouterSharedSettings = OpenRouterProviderOptions & {
 };
 
 /**
- * Usage accounting response
+ * Usage accounting response from the OpenRouter API.
  * @see https://openrouter.ai/docs/use-cases/usage-accounting
  */
 export type OpenRouterUsageAccounting = {
+  /**
+   * The number of tokens in the prompt.
+   */
   promptTokens: number;
+  /**
+   * Details about the prompt tokens.
+   */
   promptTokensDetails?: {
+    /**
+     * The number of cached tokens in the prompt.
+     */
     cachedTokens: number;
   };
+  /**
+   * The number of tokens in the completion.
+   */
   completionTokens: number;
+  /**
+   * Details about the completion tokens.
+   */
   completionTokensDetails?: {
+    /**
+     * The number of reasoning tokens in the completion.
+     */
     reasoningTokens: number;
   };
+  /**
+   * The total number of tokens.
+   */
   totalTokens: number;
+  /**
+   * The cost of the request.
+   */
   cost?: number;
+  /**
+   * Details about the cost.
+   */
   costDetails: {
+    /**
+     * The cost of the upstream inference.
+     */
     upstreamInferenceCost: number;
   };
 };
diff --git a/src/types/openrouter-chat-completions-input.ts b/src/types/openrouter-chat-completions-input.ts
index 4fb6883..5aecb75 100644
--- a/src/types/openrouter-chat-completions-input.ts
+++ b/src/types/openrouter-chat-completions-input.ts
@@ -1,78 +1,215 @@
 import type { ReasoningDetailUnion } from '@/src/schemas/reasoning-details';
 
-// Type for OpenRouter Cache Control following Anthropic's pattern
+/**
+ * Type for OpenRouter Cache Control, following Anthropic's pattern.
+ */
 export type OpenRouterCacheControl = { type: 'ephemeral' };
 
+/**
+ * The input for the OpenRouter chat completions API.
+ */
 export type OpenRouterChatCompletionsInput = Array<ChatCompletionMessageParam>;
 
+/**
+ * A message in the chat completion.
+ */
 export type ChatCompletionMessageParam =
   | ChatCompletionSystemMessageParam
   | ChatCompletionUserMessageParam
   | ChatCompletionAssistantMessageParam
   | ChatCompletionToolMessageParam;
 
+/**
+ * A system message in the chat completion.
+ */
 export interface ChatCompletionSystemMessageParam {
+  /**
+   * The role of the message.
+   */
   role: 'system';
+  /**
+   * The content of the message.
+   */
   content: string;
+  /**
+   * The cache control for the message.
+   */
   cache_control?: OpenRouterCacheControl;
 }
 
+/**
+ * A user message in the chat completion.
+ */
 export interface ChatCompletionUserMessageParam {
+  /**
+   * The role of the message.
+   */
   role: 'user';
+  /**
+   * The content of the message.
+   */
   content: string | Array<ChatCompletionContentPart>;
+  /**
+   * The cache control for the message.
+   */
   cache_control?: OpenRouterCacheControl;
 }
 
+/**
+ * A part of the content of a user message.
+ */
 export type ChatCompletionContentPart =
   | ChatCompletionContentPartText
   | ChatCompletionContentPartImage
   | ChatCompletionContentPartFile;
 
+/**
+ * A file part of the content of a user message.
+ */
 export interface ChatCompletionContentPartFile {
+  /**
+   * The type of the content part.
+   */
   type: 'file';
+  /**
+   * The file content.
+   */
   file: {
+    /**
+     * The name of the file.
+     */
     filename: string;
+    /**
+     * The data of the file.
+     */
     file_data: string;
   };
+  /**
+   * The cache control for the content part.
+   */
   cache_control?: OpenRouterCacheControl;
 }
 
+/**
+ * An image part of the content of a user message.
+ */
 export interface ChatCompletionContentPartImage {
+  /**
+   * The type of the content part.
+   */
   type: 'image_url';
+  /**
+   * The image URL.
+   */
   image_url: {
+    /**
+     * The URL of the image.
+     */
     url: string;
   };
+  /**
+   * The cache control for the content part.
+   */
   cache_control?: OpenRouterCacheControl;
 }
 
+/**
+ * A text part of the content of a user message.
+ */
 export interface ChatCompletionContentPartText {
+  /**
+   * The type of the content part.
+   */
   type: 'text';
+  /**
+   * The text content.
+   */
   text: string;
+  /**
+   * The reasoning for the text.
+   */
   reasoning?: string | null;
+  /**
+   * The cache control for the content part.
+   */
   cache_control?: OpenRouterCacheControl;
 }
 
+/**
+ * An assistant message in the chat completion.
+ */
 export interface ChatCompletionAssistantMessageParam {
+  /**
+   * The role of the message.
+   */
   role: 'assistant';
+  /**
+   * The content of the message.
+   */
   content?: string | null;
+  /**
+   * The reasoning for the message.
+   */
   reasoning?: string | null;
+  /**
+   * Details about the reasoning.
+   */
   reasoning_details?: ReasoningDetailUnion[];
+  /**
+   * The tool calls in the message.
+   */
   tool_calls?: Array<ChatCompletionMessageToolCall>;
+  /**
+   * The cache control for the message.
+   */
   cache_control?: OpenRouterCacheControl;
 }
 
+/**
+ * A tool call in an assistant message.
+ */
 export interface ChatCompletionMessageToolCall {
+  /**
+   * The type of the tool call.
+   */
   type: 'function';
+  /**
+   * The ID of the tool call.
+   */
   id: string;
+  /**
+   * The function that was called.
+   */
   function: {
+    /**
+     * The arguments of the function.
+     */
     arguments: string;
+    /**
+     * The name of the function.
+     */
     name: string;
   };
 }
 
+/**
+ * A tool message in the chat completion.
+ */
 export interface ChatCompletionToolMessageParam {
+  /**
+   * The role of the message.
+   */
   role: 'tool';
+  /**
+   * The content of the message.
+   */
   content: string;
+  /**
+   * The ID of the tool call that this message is a response to.
+   */
   tool_call_id: string;
+  /**
+   * The cache control for the message.
+   */
   cache_control?: OpenRouterCacheControl;
 }
diff --git a/src/types/openrouter-chat-settings.ts b/src/types/openrouter-chat-settings.ts
index 9238b27..be93d3f 100644
--- a/src/types/openrouter-chat-settings.ts
+++ b/src/types/openrouter-chat-settings.ts
@@ -1,108 +1,117 @@
 import type { OpenRouterSharedSettings } from '..';
 
-// https://openrouter.ai/api/v1/models
+/**
+ * The ID of an OpenRouter chat model.
+ * @see https://openrouter.ai/api/v1/models
+ */
 export type OpenRouterChatModelId = string;
 
+/**
+ * Settings for an OpenRouter chat model.
+ */
 export type OpenRouterChatSettings = {
   /**
-Modify the likelihood of specified tokens appearing in the completion.
-
-Accepts a JSON object that maps tokens (specified by their token ID in
-the GPT tokenizer) to an associated bias value from -100 to 100. You
-can use this tokenizer tool to convert text to token IDs. Mathematically,
-the bias is added to the logits generated by the model prior to sampling.
-The exact effect will vary per model, but values between -1 and 1 should
-decrease or increase likelihood of selection; values like -100 or 100
-should result in a ban or exclusive selection of the relevant token.
-
-As an example, you can pass {"50256": -100} to prevent the <|endoftext|>
-token from being generated.
-*/
+   * Modify the likelihood of specified tokens appearing in the completion.
+   *
+   * Accepts a JSON object that maps tokens (specified by their token ID in
+   * the GPT tokenizer) to an associated bias value from -100 to 100. You
+   * can use this tokenizer tool to convert text to token IDs. Mathematically,
+   * the bias is added to the logits generated by the model prior to sampling.
+   * The exact effect will vary per model, but values between -1 and 1 should
+   * decrease or increase likelihood of selection; values like -100 or 100
+   * should result in a ban or exclusive selection of the relevant token.
+   *
+   * As an example, you can pass `{"50256": -100}` to prevent the `<|endoftext|>`
+   * token from being generated.
+   */
   logitBias?: Record<number, number>;
 
   /**
-Return the log probabilities of the tokens. Including logprobs will increase
-the response size and can slow down response times. However, it can
-be useful to understand better how the model is behaving.
-
-Setting to true will return the log probabilities of the tokens that
-were generated.
-
-Setting to a number will return the log probabilities of the top n
-tokens that were generated.
-*/
+   * Return the log probabilities of the tokens. Including logprobs will increase
+   * the response size and can slow down response times. However, it can
+   * be useful to understand better how the model is behaving.
+   *
+   * Setting to `true` will return the log probabilities of the tokens that
+   * were generated.
+   *
+   * Setting to a number will return the log probabilities of the top n
+   * tokens that were generated.
+   */
   logprobs?: boolean | number;
 
   /**
-Whether to enable parallel function calling during tool use. Default to true.
+   * Whether to enable parallel function calling during tool use. Default to `true`.
    */
   parallelToolCalls?: boolean;
 
   /**
-A unique identifier representing your end-user, which can help OpenRouter to
-monitor and detect abuse. Learn more.
-*/
+   * A unique identifier representing your end-user, which can help OpenRouter to
+   * monitor and detect abuse.
+   */
   user?: string;
 
   /**
-   * Web search plugin configuration for enabling web search capabilities
+   * Web search plugin configuration for enabling web search capabilities.
    */
   plugins?: Array<{
+    /**
+     * The ID of the plugin.
+     */
     id: 'web';
     /**
-     * Maximum number of search results to include (default: 5)
+     * Maximum number of search results to include (default: 5).
      */
     max_results?: number;
     /**
-     * Custom search prompt to guide the search query
+     * Custom search prompt to guide the search query.
      */
     search_prompt?: string;
   }>;
 
   /**
-   * Built-in web search options for models that support native web search
+   * Built-in web search options for models that support native web search.
    */
   web_search_options?: {
     /**
-     * Maximum number of search results to include
+     * Maximum number of search results to include.
      */
     max_results?: number;
     /**
-     * Custom search prompt to guide the search query
+     * Custom search prompt to guide the search query.
      */
     search_prompt?: string;
   };
 
   /**
-   * Provider routing preferences to control request routing behavior
+   * Provider routing preferences to control request routing behavior.
    */
   provider?: {
     /**
-     * List of provider slugs to try in order (e.g. ["anthropic", "openai"])
+     * List of provider slugs to try in order (e.g. `["anthropic", "openai"]`).
      */
     order?: string[];
     /**
-     * Whether to allow backup providers when primary is unavailable (default: true)
+     * Whether to allow backup providers when primary is unavailable (default: `true`).
      */
     allow_fallbacks?: boolean;
     /**
-     * Only use providers that support all parameters in your request (default: false)
+     * Only use providers that support all parameters in your request (default: `false`).
      */
     require_parameters?: boolean;
     /**
-     * Control whether to use providers that may store data
+     * Control whether to use providers that may store data.
      */
     data_collection?: 'allow' | 'deny';
     /**
-     * List of provider slugs to allow for this request
+     * List of provider slugs to allow for this request.
      */
     only?: string[];
     /**
-     * List of provider slugs to skip for this request
+     * List of provider slugs to skip for this request.
      */
     ignore?: string[];
     /**
-     * List of quantization levels to filter by (e.g. ["int4", "int8"])
+     * List of quantization levels to filter by (e.g. `["int4", "int8"]`).
      */
     quantizations?: Array<
       | 'int4'
@@ -116,17 +125,32 @@ monitor and detect abuse. Learn more.
       | 'unknown'
     >;
     /**
-     * Sort providers by price, throughput, or latency
+     * Sort providers by price, throughput, or latency.
      */
     sort?: 'price' | 'throughput' | 'latency';
     /**
-     * Maximum pricing you want to pay for this request
+     * Maximum pricing you want to pay for this request.
      */
     max_price?: {
+      /**
+       * The maximum price for the prompt.
+       */
       prompt?: number | string;
+      /**
+       * The maximum price for the completion.
+       */
       completion?: number | string;
+      /**
+       * The maximum price for an image.
+       */
       image?: number | string;
+      /**
+       * The maximum price for audio.
+       */
       audio?: number | string;
+      /**
+       * The maximum price for the request.
+       */
       request?: number | string;
     };
   };
diff --git a/src/types/openrouter-completion-settings.ts b/src/types/openrouter-completion-settings.ts
index b5f6b99..2077faa 100644
--- a/src/types/openrouter-completion-settings.ts
+++ b/src/types/openrouter-completion-settings.ts
@@ -1,39 +1,45 @@
 import type { OpenRouterSharedSettings } from '.';
 
+/**
+ * The ID of an OpenRouter completion model.
+ */
 export type OpenRouterCompletionModelId = string;
 
+/**
+ * Settings for an OpenRouter completion model.
+ */
 export type OpenRouterCompletionSettings = {
   /**
-Modify the likelihood of specified tokens appearing in the completion.
-
-Accepts a JSON object that maps tokens (specified by their token ID in
-the GPT tokenizer) to an associated bias value from -100 to 100. You
-can use this tokenizer tool to convert text to token IDs. Mathematically,
-the bias is added to the logits generated by the model prior to sampling.
-The exact effect will vary per model, but values between -1 and 1 should
-decrease or increase likelihood of selection; values like -100 or 100
-should result in a ban or exclusive selection of the relevant token.
-
-As an example, you can pass {"50256": -100} to prevent the <|endoftext|>
-token from being generated.
+   * Modify the likelihood of specified tokens appearing in the completion.
+   *
+   * Accepts a JSON object that maps tokens (specified by their token ID in
+   * the GPT tokenizer) to an associated bias value from -100 to 100. You
+   * can use this tokenizer tool to convert text to token IDs. Mathematically,
+   * the bias is added to the logits generated by the model prior to sampling.
+   * The exact effect will vary per model, but values between -1 and 1 should
+   * decrease or increase likelihood of selection; values like -100 or 100
+   * should result in a ban or exclusive selection of the relevant token.
+   *
+   * As an example, you can pass `{"50256": -100}` to prevent the `<|endoftext|>`
+   * token from being generated.
    */
   logitBias?: Record<number, number>;
 
   /**
-Return the log probabilities of the tokens. Including logprobs will increase
-the response size and can slow down response times. However, it can
-be useful to better understand how the model is behaving.
-
-Setting to true will return the log probabilities of the tokens that
-were generated.
-
-Setting to a number will return the log probabilities of the top n
-tokens that were generated.
+   * Return the log probabilities of the tokens. Including logprobs will increase
+   * the response size and can slow down response times. However, it can
+   * be useful to better understand how the model is behaving.
+   *
+   * Setting to `true` will return the log probabilities of the tokens that
+   * were generated.
+   *
+   * Setting to a number will return the log probabilities of the top n
+   * tokens that were generated.
    */
   logprobs?: boolean | number;
 
   /**
-The suffix that comes after a completion of inserted text.
+   * The suffix that comes after a completion of inserted text.
    */
   suffix?: string;
 } & OpenRouterSharedSettings;
diff --git a/src/utils/map-finish-reason.ts b/src/utils/map-finish-reason.ts
index e3c3f9b..5fe0794 100644
--- a/src/utils/map-finish-reason.ts
+++ b/src/utils/map-finish-reason.ts
@@ -1,5 +1,11 @@
 import type { LanguageModelV2FinishReason } from '@ai-sdk/provider';
 
+/**
+ * Maps an OpenRouter finish reason to a language model finish reason.
+ *
+ * @param {string | null | undefined} finishReason - The finish reason from OpenRouter.
+ * @returns {LanguageModelV2FinishReason} The mapped finish reason.
+ */
 export function mapOpenRouterFinishReason(
   finishReason: string | null | undefined,
 ): LanguageModelV2FinishReason {