fix: respect user-specified User-Agent headers without modification (OpenRouterTeam#362)

* fix: respect user-specified User-Agent headers without modification

- Add case-insensitive lookup for User-Agent header
- When user provides User-Agent (any case), use it verbatim without SDK suffix
- Only add SDK identifier as default when no User-Agent is provided
- Add comprehensive tests for withUserAgentSuffix function

Fixes OpenRouterTeam#300

Co-Authored-By: Robert Yeakel <robert.yeakel@openrouter.ai>

* fix: handle all HeadersInit variants and fix removeUndefinedEntries

- Add normalizeHeaders() to properly handle Headers objects and array-of-tuples
- Fix removeUndefinedEntries to filter both null and undefined values
- Add tests for Headers object and array-of-tuples inputs
- Update test to verify undefined keys are actually removed from result

Co-Authored-By: Robert Yeakel <robert.yeakel@openrouter.ai>

---------

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

Author: robert-j-y

.changeset/fix-user-agent-header-override.md

@@ -0,0 +1,13 @@
+---
+"@openrouter/ai-sdk-provider": patch
+---
+
+fix: respect user-specified User-Agent headers without modification
+
+Previously, when users provided a custom `User-Agent` header via `createOpenRouter({ headers: { 'User-Agent': 'my-app/1.0' } })`, the SDK would append its identifier to the header, resulting in `my-app/1.0, ai-sdk/openrouter/x.x.x`. This was unexpected behavior.
+
+Now, user-specified `User-Agent` headers are used verbatim without modification. The SDK identifier is only added as the default when no `User-Agent` header is provided.
+
+This also fixes a case-sensitivity bug where `User-Agent` (capitalized) was not recognized as the same header as `user-agent` (lowercase), causing duplicate headers to be sent.
+
+Fixes #300

src/utils/remove-undefined.ts

@@ -7,6 +7,6 @@ export function removeUndefinedEntries<T>(
   record: Record<string, T | undefined>,
 ): Record<string, T> {
   return Object.fromEntries(
-    Object.entries(record).filter(([, value]) => value !== null),
+    Object.entries(record).filter(([, value]) => value != null),
   ) as Record<string, T>;
 }

src/utils/with-user-agent-suffix.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest';
+import { withUserAgentSuffix } from './with-user-agent-suffix';
+
+describe('withUserAgentSuffix', () => {
+  const SDK_SUFFIX = 'ai-sdk/openrouter/1.0.0';
+
+  describe('when no user-agent header is provided', () => {
+    it('should add SDK identifier as the user-agent', () => {
+      const result = withUserAgentSuffix({}, SDK_SUFFIX);
+      expect(result['user-agent']).toBe(SDK_SUFFIX);
+    });
+
+    it('should add SDK identifier when headers is undefined', () => {
+      const result = withUserAgentSuffix(undefined, SDK_SUFFIX);
+      expect(result['user-agent']).toBe(SDK_SUFFIX);
+    });
+
+    it('should preserve other headers while adding user-agent', () => {
+      const result = withUserAgentSuffix(
+        { Authorization: 'Bearer token', 'Content-Type': 'application/json' },
+        SDK_SUFFIX,
+      );
+      expect(result['user-agent']).toBe(SDK_SUFFIX);
+      expect(result['Authorization']).toBe('Bearer token');
+      expect(result['Content-Type']).toBe('application/json');
+    });
+  });
+
+  describe('when user provides user-agent header', () => {
+    it('should use user-provided lowercase user-agent verbatim without SDK suffix', () => {
+      const result = withUserAgentSuffix(
+        { 'user-agent': 'my-custom-agent/1.0' },
+        SDK_SUFFIX,
+      );
+      expect(result['user-agent']).toBe('my-custom-agent/1.0');
+    });
+
+    it('should use user-provided capitalized User-Agent verbatim without SDK suffix', () => {
+      const result = withUserAgentSuffix(
+        { 'User-Agent': 'my-custom-agent/1.0' },
+        SDK_SUFFIX,
+      );
+      expect(result['user-agent']).toBe('my-custom-agent/1.0');
+      // Should not have duplicate header with different casing
+      expect(result['User-Agent']).toBeUndefined();
+    });
+
+    it('should use user-provided mixed case USER-AGENT verbatim without SDK suffix', () => {
+      const result = withUserAgentSuffix(
+        { 'USER-AGENT': 'my-custom-agent/1.0' },
+        SDK_SUFFIX,
+      );
+      expect(result['user-agent']).toBe('my-custom-agent/1.0');
+      // Should not have duplicate header with different casing
+      expect(result['USER-AGENT']).toBeUndefined();
+    });
+
+    it('should preserve other headers when user provides User-Agent', () => {
+      const result = withUserAgentSuffix(
+        {
+          'User-Agent': 'my-custom-agent/1.0',
+          Authorization: 'Bearer token',
+        },
+        SDK_SUFFIX,
+      );
+      expect(result['user-agent']).toBe('my-custom-agent/1.0');
+      expect(result['Authorization']).toBe('Bearer token');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should use SDK identifier when user-agent is empty string', () => {
+      const result = withUserAgentSuffix({ 'user-agent': '' }, SDK_SUFFIX);
+      expect(result['user-agent']).toBe(SDK_SUFFIX);
+    });
+
+    it('should handle multiple suffix parts when no user-agent provided', () => {
+      const result = withUserAgentSuffix({}, 'part1', 'part2');
+      expect(result['user-agent']).toBe('part1 part2');
+    });
+
+    it('should remove undefined header values and not include the key', () => {
+      const result = withUserAgentSuffix(
+        { 'some-header': undefined as unknown as string },
+        SDK_SUFFIX,
+      );
+      expect('some-header' in result).toBe(false);
+      expect(result['user-agent']).toBe(SDK_SUFFIX);
+    });
+  });
+
+  describe('HeadersInit variants', () => {
+    it('should handle Headers object input', () => {
+      const headers = new Headers({
+        Authorization: 'Bearer token',
+        'User-Agent': 'my-custom-agent/1.0',
+      });
+      const result = withUserAgentSuffix(headers, SDK_SUFFIX);
+      expect(result['user-agent']).toBe('my-custom-agent/1.0');
+      expect(result['authorization']).toBe('Bearer token');
+    });
+
+    it('should handle Headers object without user-agent', () => {
+      const headers = new Headers({
+        Authorization: 'Bearer token',
+      });
+      const result = withUserAgentSuffix(headers, SDK_SUFFIX);
+      expect(result['user-agent']).toBe(SDK_SUFFIX);
+      expect(result['authorization']).toBe('Bearer token');
+    });
+
+    it('should handle array-of-tuples input', () => {
+      const headers: [string, string][] = [
+        ['Authorization', 'Bearer token'],
+        ['User-Agent', 'my-custom-agent/1.0'],
+      ];
+      const result = withUserAgentSuffix(headers, SDK_SUFFIX);
+      expect(result['user-agent']).toBe('my-custom-agent/1.0');
+      expect(result['Authorization']).toBe('Bearer token');
+    });
+
+    it('should handle array-of-tuples without user-agent', () => {
+      const headers: [string, string][] = [
+        ['Authorization', 'Bearer token'],
+        ['Content-Type', 'application/json'],
+      ];
+      const result = withUserAgentSuffix(headers, SDK_SUFFIX);
+      expect(result['user-agent']).toBe(SDK_SUFFIX);
+      expect(result['Authorization']).toBe('Bearer token');
+      expect(result['Content-Type']).toBe('application/json');
+    });
+  });
+});

src/utils/with-user-agent-suffix.ts

@@ -1,30 +1,78 @@
 import { removeUndefinedEntries } from '@/src/utils/remove-undefined';
 
 /**
- * Appends suffix parts to the `user-agent` header.
- * If a `user-agent` header already exists, the suffix parts are appended to it.
- * If no `user-agent` header exists, a new one is created with the suffix parts.
+ * Normalizes HeadersInit to a plain object.
+ * Handles Headers objects, array-of-tuples, and plain objects.
+ * @param headers - The headers in any HeadersInit format.
+ * @returns A plain object with string keys and values.
+ */
+function normalizeHeaders(
+  headers: HeadersInit | Record<string, string | undefined> | undefined,
+): Record<string, string | undefined> {
+  if (!headers) {
+    return {};
+  }
+  if (headers instanceof Headers) {
+    return Object.fromEntries(headers.entries());
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return headers as Record<string, string | undefined>;
+}
+
+/**
+ * Finds a header key in a case-insensitive manner.
+ * @param headers - The headers object to search.
+ * @param targetKey - The key to find (case-insensitive).
+ * @returns The actual key in the headers object, or undefined if not found.
+ */
+function findHeaderKey(
+  headers: Record<string, string>,
+  targetKey: string,
+): string | undefined {
+  const lowerTarget = targetKey.toLowerCase();
+  return Object.keys(headers).find((key) => key.toLowerCase() === lowerTarget);
+}
+
+/**
+ * Sets the user-agent header, respecting user-specified values.
+ * If a user explicitly provides a User-Agent header (any case), it is used verbatim.
+ * If no User-Agent header is provided, the suffix parts are used as the default.
  * Automatically removes undefined entries from the headers.
  *
  * @param headers - The original headers.
- * @param userAgentSuffixParts - The parts to append to the `user-agent` header.
- * @returns The new headers with the `user-agent` header set or updated.
+ * @param userAgentSuffixParts - The parts to use as the default user-agent if none is provided.
+ * @returns The new headers with the `user-agent` header set.
  */
 export function withUserAgentSuffix(
   headers: HeadersInit | Record<string, string | undefined> | undefined,
   ...userAgentSuffixParts: string[]
 ): Record<string, string> {
-  const cleanedHeaders = removeUndefinedEntries(
-    (headers as Record<string, string | undefined>) ?? {},
-  );
+  const normalizedHeaders = normalizeHeaders(headers);
+  const cleanedHeaders = removeUndefinedEntries(normalizedHeaders);
 
-  const currentUserAgentHeader = cleanedHeaders['user-agent'] || '';
-  const newUserAgent = [currentUserAgentHeader, ...userAgentSuffixParts]
-    .filter(Boolean)
-    .join(' ');
+  // Find user-agent header with case-insensitive lookup
+  const existingUserAgentKey = findHeaderKey(cleanedHeaders, 'user-agent');
+  const existingUserAgentValue = existingUserAgentKey
+    ? cleanedHeaders[existingUserAgentKey]
+    : undefined;
+
+  // If user provided a non-empty User-Agent, use it verbatim
+  // Otherwise, use the SDK identifier as the default
+  const userAgent = existingUserAgentValue?.trim()
+    ? existingUserAgentValue
+    : userAgentSuffixParts.filter(Boolean).join(' ');
+
+  // Remove any existing user-agent header (regardless of case) and add normalized one
+  const headersWithoutUserAgent = Object.fromEntries(
+    Object.entries(cleanedHeaders).filter(
+      ([key]) => key.toLowerCase() !== 'user-agent',
+    ),
+  );
 
   return {
-    ...cleanedHeaders,
-    'user-agent': newUserAgent,
+    ...headersWithoutUserAgent,
+    'user-agent': userAgent,
   };
 }