feat: add web search support (#144)

* feat: add web search support

- Add plugins and web_search_options for web search configuration
- Add web search annotations with corrected url_citation schema
- Support web search citation processing in responses
- Use proper AI SDK LanguageModelV2Source content types for citations

Co-Authored-By: Louis   <louis@openrouter.ai>

* test: add e2e tests for web search functionality

- Test plugins array configuration with web search plugin
- Test web_search_options for models with built-in web search
- Validate LanguageModelV2Source content in streaming responses
- Ensure proper citation handling with url, title, and sourceType

Co-Authored-By: Louis   <louis@openrouter.ai>

* refactor: replace any[] with proper type in web search e2e test

Co-Authored-By: Louis   <louis@openrouter.ai>

* refactor: replace any[] with proper type for sources array in web search e2e test

Co-Authored-By: Louis   <louis@openrouter.ai>

* update tests and schema

* bump version

* fix

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: louisgv

e2e/usage-accounting.test.ts

@@ -1,7 +1,11 @@
 import { streamText } from 'ai';
-import { it } from 'vitest';
+import { it, vi } from 'vitest';
 import { createOpenRouter } from '@/src';
 
+vi.setConfig({
+  testTimeout: 60_000,
+});
+
 it('receive usage accounting', async () => {
   const openrouter = createOpenRouter({
     apiKey: process.env.OPENROUTER_API_KEY,
@@ -38,6 +42,7 @@ it('receive usage accounting', async () => {
   const providerMetadata = await response.providerMetadata;
   // You can use expect.any(Type) or expect.objectContaining for schema-like matching
   expect(providerMetadata?.openrouter).toMatchObject({
+    provider: 'Anthropic',
     usage: expect.objectContaining({
       promptTokens: expect.any(Number),
       completionTokens: expect.any(Number),

e2e/web-search/index.test.ts

@@ -0,0 +1,50 @@
+import { streamText } from 'ai';
+import { writeFile } from 'fs/promises';
+import { describe, expect, it, vi } from 'vitest';
+import { createOpenRouter } from '@/src';
+
+vi.setConfig({
+  testTimeout: 60_000,
+});
+
+describe('Web Search E2E Tests', () => {
+  it('should handle web search citations in streaming response', async () => {
+    const openrouter = createOpenRouter({
+      apiKey: process.env.OPENROUTER_API_KEY,
+      baseUrl: `${process.env.OPENROUTER_API_BASE}/api/v1`,
+    });
+
+    const model = openrouter('anthropic/claude-3.5-sonnet', {
+      plugins: [
+        {
+          id: 'web',
+          max_results: 2,
+        },
+      ],
+      usage: {
+        include: true,
+      },
+    });
+
+    const response = streamText({
+      model,
+      messages: [
+        {
+          role: 'user',
+          content: 'Tell me about the latest SpaceX launch with sources.',
+        },
+      ],
+    });
+
+    await response.consumeStream();
+
+    const sources = await response.sources;
+
+    expect(sources.length).toBe(2);
+
+    await writeFile(
+      new URL('./output.ignore.json', import.meta.url),
+      JSON.stringify(sources, null, 2),
+    );
+  });
+});

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openrouter/ai-sdk-provider",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

src/chat/index.ts

@@ -131,6 +131,9 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
       reasoning: this.settings.reasoning,
       usage: this.settings.usage,
 
+      // Web search settings:
+      plugins: this.settings.plugins,
+      web_search_options: this.settings.web_search_options,
       // Provider routing settings:
       provider: this.settings.provider,
 
@@ -188,6 +191,7 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
     warnings: Array<LanguageModelV2CallWarning>;
     providerMetadata?: {
       openrouter: {
+        provider: string;
         usage: OpenRouterUsageAccounting;
       };
     };
@@ -321,13 +325,33 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
       }
     }
 
+    if (choice.message.annotations) {
+      for (const annotation of choice.message.annotations) {
+        if (annotation.type === 'url_citation') {
+          content.push({
+            type: 'source' as const,
+            sourceType: 'url' as const,
+            id: annotation.url_citation.url,
+            url: annotation.url_citation.url,
+            title: annotation.url_citation.title,
+            providerMetadata: {
+              openrouter: {
+                content: annotation.url_citation.content || '',
+              },
+            },
+          });
+        }
+      }
+    }
+
     return {
       content,
       finishReason: mapOpenRouterFinishReason(choice.finish_reason),
       usage: usageInfo,
       warnings: [],
       providerMetadata: {
         openrouter: {
+          provider: response.provider ?? '',
           usage: {
             promptTokens: usageInfo.inputTokens ?? 0,
             completionTokens: usageInfo.outputTokens ?? 0,
@@ -433,6 +457,7 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
     let textId: string | undefined;
     let reasoningId: string | undefined;
     let openrouterResponseId: string | undefined;
+    let provider: string | undefined;
 
     return {
       stream: response.pipeThrough(
@@ -459,6 +484,10 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
               return;
             }
 
+            if (value.provider) {
+              provider = value.provider;
+            }
+
             if (value.id) {
               openrouterResponseId = value.id;
               controller.enqueue({
@@ -577,7 +606,7 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
                 });
                 reasoningStarted = false; // Mark as ended so we don't end it again in flush
               }
-              
+
               if (!textStarted) {
                 textId = openrouterResponseId || generateId();
                 controller.enqueue({
@@ -593,6 +622,25 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
               });
             }
 
+            if (delta.annotations) {
+              for (const annotation of delta.annotations) {
+                if (annotation.type === 'url_citation') {
+                  controller.enqueue({
+                    type: 'source',
+                    sourceType: 'url' as const,
+                    id: annotation.url_citation.url,
+                    url: annotation.url_citation.url,
+                    title: annotation.url_citation.title,
+                    providerMetadata: {
+                      openrouter: {
+                        content: annotation.url_citation.content || '',
+                      },
+                    },
+                  });
+                }
+              }
+            }
+
             if (delta.tool_calls != null) {
               for (const toolCallDelta of delta.tool_calls) {
                 const index = toolCallDelta.index ?? toolCalls.length - 1;
@@ -757,14 +805,24 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
               });
             }
 
+            const openrouterMetadata: {
+              usage: Partial<OpenRouterUsageAccounting>;
+              provider?: string;
+            } = {
+              usage: openrouterUsage,
+            };
+            
+            // Only include provider if it's actually set
+            if (provider !== undefined) {
+              openrouterMetadata.provider = provider;
+            }
+            
             controller.enqueue({
               type: 'finish',
               finishReason,
               usage,
               providerMetadata: {
-                openrouter: {
-                  usage: openrouterUsage,
-                },
+                openrouter: openrouterMetadata,
               },
             });
           },

src/chat/schemas.ts

@@ -5,6 +5,7 @@ import { ReasoningDetailArraySchema } from '../schemas/reasoning-details';
 const OpenRouterChatCompletionBaseResponseSchema = z.object({
   id: z.string().optional(),
   model: z.string().optional(),
+  provider: z.string().optional(),
   usage: z
     .object({
       prompt_tokens: z.number(),
@@ -53,6 +54,21 @@ export const OpenRouterNonStreamChatCompletionResponseSchema =
               }),
             )
             .optional(),
+
+          annotations: z
+            .array(
+              z.object({
+                type: z.enum(['url_citation']),
+                url_citation: z.object({
+                  end_index: z.number(),
+                  start_index: z.number(),
+                  title: z.string(),
+                  url: z.string(),
+                  content: z.string().optional(),
+                }),
+              }),
+            )
+            .nullish(),
         }),
         index: z.number().nullish(),
         logprobs: z
@@ -103,6 +119,21 @@ export const OpenRouterStreamChatCompletionChunkSchema = z.union([
                 }),
               )
               .nullish(),
+
+            annotations: z
+              .array(
+                z.object({
+                  type: z.enum(['url_citation']),
+                  url_citation: z.object({
+                    end_index: z.number(),
+                    start_index: z.number(),
+                    title: z.string(),
+                    url: z.string(),
+                    content: z.string().optional(),
+                  }),
+                }),
+              )
+              .nullish(),
           })
           .nullish(),
         logprobs: z

src/types/openrouter-chat-settings.ts

@@ -44,6 +44,35 @@ monitor and detect abuse. Learn more.
 */
   user?: string;
 
+  /**
+   * Web search plugin configuration for enabling web search capabilities
+   */
+  plugins?: Array<{
+    id: 'web';
+    /**
+     * Maximum number of search results to include (default: 5)
+     */
+    max_results?: number;
+    /**
+     * Custom search prompt to guide the search query
+     */
+    search_prompt?: string;
+  }>;
+
+  /**
+   * Built-in web search options for models that support native web search
+   */
+  web_search_options?: {
+    /**
+     * Maximum number of search results to include
+     */
+    max_results?: number;
+    /**
+     * Custom search prompt to guide the search query
+     */
+    search_prompt?: string;
+  };
+
   /**
    * Provider routing preferences to control request routing behavior
    */
@@ -75,7 +104,17 @@ monitor and detect abuse. Learn more.
     /**
      * List of quantization levels to filter by (e.g. ["int4", "int8"])
      */
-    quantizations?: Array<'int4' | 'int8' | 'fp4' | 'fp6' | 'fp8' | 'fp16' | 'bf16' | 'fp32' | 'unknown'>;
+    quantizations?: Array<
+      | 'int4'
+      | 'int8'
+      | 'fp4'
+      | 'fp6'
+      | 'fp8'
+      | 'fp16'
+      | 'bf16'
+      | 'fp32'
+      | 'unknown'
+    >;
     /**
      * Sort providers by price, throughput, or latency
      */