feat(openrouter): default OpenRouter attribution headers (#10109)

Author: hntrl

.changeset/openrouter-attribution-headers.md

@@ -0,0 +1,7 @@
+---
+"@langchain/openrouter": patch
+---
+
+feat(openrouter): default OpenRouter attribution headers
+
+`ChatOpenRouter` now sends `HTTP-Referer` and `X-Title` headers by default for OpenRouter app attribution. `siteUrl` defaults to `"https://docs.langchain.com/oss"` and `siteName` defaults to `"langchain"`. Users can still override both values.

libs/providers/langchain-openrouter/src/chat_models/index.ts

@@ -206,11 +206,19 @@ export class ChatOpenRouter extends BaseChatModel<
   /** OpenRouter plugins to enable (e.g. web search). */
   plugins?: ChatOpenRouterParams["plugins"];
 
-  /** Your site URL — used for rankings on openrouter.ai. */
-  siteUrl?: string;
+  /**
+   * Application URL for OpenRouter attribution. Maps to `HTTP-Referer` header.
+   *
+   * See https://openrouter.ai/docs/app-attribution for details.
+   */
+  siteUrl: string;
 
-  /** Your site/app name — used for rankings on openrouter.ai. */
-  siteName?: string;
+  /**
+   * Application title for OpenRouter attribution. Maps to `X-Title` header.
+   *
+   * See https://openrouter.ai/docs/app-attribution for details.
+   */
+  siteName: string;
 
   /** Extra params passed through to the API body. */
   modelKwargs?: Record<string, unknown>;
@@ -254,8 +262,8 @@ export class ChatOpenRouter extends BaseChatModel<
     this.route = fields.route;
     this.provider = fields.provider;
     this.plugins = fields.plugins;
-    this.siteUrl = fields.siteUrl;
-    this.siteName = fields.siteName;
+    this.siteUrl = fields.siteUrl ?? "https://docs.langchain.com/oss";
+    this.siteName = fields.siteName ?? "langchain";
     this.modelKwargs = fields.modelKwargs;
     this.streamUsage = fields.streamUsage ?? true;
   }
@@ -274,8 +282,8 @@ export class ChatOpenRouter extends BaseChatModel<
     return {
       Authorization: `Bearer ${this.apiKey}`,
       "Content-Type": "application/json",
-      ...(this.siteUrl ? { "HTTP-Referer": this.siteUrl } : {}),
-      ...(this.siteName ? { "X-Title": this.siteName } : {}),
+      "HTTP-Referer": this.siteUrl,
+      "X-Title": this.siteName,
     };
   }
 

libs/providers/langchain-openrouter/src/chat_models/tests/index.test.ts

@@ -77,6 +77,22 @@ describe("ChatOpenRouter constructor", () => {
     expect(model.streamUsage).toBe(true);
   });
 
+  it("defaults siteUrl and siteName for OpenRouter attribution", () => {
+    const model = new ChatOpenRouter({ model: "openai/gpt-4o" });
+    expect(model.siteUrl).toBe("https://docs.langchain.com/oss");
+    expect(model.siteName).toBe("langchain");
+  });
+
+  it("allows user to override siteUrl and siteName", () => {
+    const model = new ChatOpenRouter({
+      model: "openai/gpt-4o",
+      siteUrl: "https://my-custom-app.com",
+      siteName: "My Custom App",
+    });
+    expect(model.siteUrl).toBe("https://my-custom-app.com");
+    expect(model.siteName).toBe("My Custom App");
+  });
+
   it("throws OpenRouterAuthError when no API key is available", () => {
     const original = process.env.OPENROUTER_API_KEY;
     delete process.env.OPENROUTER_API_KEY;

libs/providers/langchain-openrouter/src/chat_models/types.ts

@@ -71,9 +71,19 @@ export interface ChatOpenRouterParams
   apiKey?: string;
   /** Base URL for the API. Defaults to "https://openrouter.ai/api/v1". */
   baseURL?: string;
-  /** Your site URL — used for OpenRouter rankings / rate limits. */
+  /**
+   * Application URL for OpenRouter attribution. Maps to `HTTP-Referer` header.
+   * Defaults to `"https://docs.langchain.com/oss"`.
+   *
+   * See https://openrouter.ai/docs/app-attribution for details.
+   */
   siteUrl?: string;
-  /** Your site name — shown on the OpenRouter leaderboard. */
+  /**
+   * Application title for OpenRouter attribution. Maps to `X-Title` header.
+   * Defaults to `"langchain"`.
+   *
+   * See https://openrouter.ai/docs/app-attribution for details.
+   */
   siteName?: string;
   /** Stable identifier for end-users, used for abuse detection. */
   user?: string;