fix: address Perplexity adapter review feedback

Author: jliounis

packages/typescript/ai-perplexity/package.json

@@ -51,7 +51,7 @@
     "openai": "^6.9.1"
   },
   "devDependencies": {
-    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai": "workspace:^",
     "@vitest/coverage-v8": "4.0.14",
     "vite": "^7.2.7"
   },

packages/typescript/ai-perplexity/src/chat/client.ts

@@ -34,9 +34,14 @@ export function createPerplexityChatClient(
   config: PerplexityChatClientConfig = {},
 ): OpenAI {
   const { apiKey, baseURL, ...rest } = config
+  const resolvedApiKey =
+    typeof apiKey === 'string' && apiKey.trim().length > 0
+      ? apiKey
+      : getPerplexityApiKeyFromEnv()
+
   return new OpenAI({
     ...rest,
-    apiKey: apiKey ?? getPerplexityApiKeyFromEnv(),
+    apiKey: resolvedApiKey,
     baseURL: baseURL ?? DEFAULT_BASE_URL,
   })
 }

packages/typescript/ai-perplexity/src/search/client.ts

@@ -57,7 +57,13 @@ export class PerplexitySearchClient {
   private readonly fetchImpl: typeof fetch
 
   constructor(config: PerplexitySearchClientConfig = {}) {
-    this.apiKey = config.apiKey ?? getPerplexityApiKeyFromEnv()
+    const { apiKey } = config
+    const resolvedApiKey =
+      typeof apiKey === 'string' && apiKey.trim().length > 0
+        ? apiKey
+        : getPerplexityApiKeyFromEnv()
+
+    this.apiKey = resolvedApiKey
     this.baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, '')
     this.fetchImpl = config.fetch ?? globalThis.fetch
   }
@@ -66,13 +72,15 @@ export class PerplexitySearchClient {
     request: PerplexitySearchRequest,
     init: { signal?: AbortSignal } = {},
   ): Promise<PerplexitySearchResponse> {
-    if (!request.query || typeof request.query !== 'string') {
+    const query = typeof request.query === 'string' ? request.query.trim() : ''
+    if (query.length === 0) {
       throw new Error('PerplexitySearchClient.search requires a non-empty `query`.')
     }
     validateDomainFilter(request.search_domain_filter)
 
-    const body: Record<string, unknown> = { query: request.query }
-    if (request.max_results !== undefined) body.max_results = request.max_results
+    const body: Record<string, unknown> = { query }
+    if (request.max_results !== undefined)
+      body.max_results = clampMaxResults(request.max_results)
     if (request.max_tokens_per_page !== undefined)
       body.max_tokens_per_page = request.max_tokens_per_page
     if (request.search_domain_filter)
@@ -119,6 +127,13 @@ export class PerplexitySearchClient {
   }
 }
 
+function clampMaxResults(maxResults: number): number {
+  if (!Number.isFinite(maxResults)) {
+    throw new Error('max_results must be a finite number.')
+  }
+  return Math.min(20, Math.max(1, Math.trunc(maxResults)))
+}
+
 function validateDomainFilter(filter: Array<string> | undefined): void {
   if (!filter || filter.length === 0) return
   let hasAllow = false

packages/typescript/ai-perplexity/src/search/tool.ts

@@ -34,6 +34,14 @@ export function perplexitySearchTool(
     defaultMaxResults,
     ...clientConfig
   } = config
+  if (
+    defaultMaxResults !== undefined &&
+    (!Number.isInteger(defaultMaxResults) ||
+      defaultMaxResults < 1 ||
+      defaultMaxResults > 20)
+  ) {
+    throw new Error('defaultMaxResults must be an integer between 1 and 20.')
+  }
 
   // Lazily construct the client so missing API keys don't blow up at import
   // time (e.g. on bundlers that statically evaluate module top-level).

packages/typescript/ai-perplexity/src/utils/api-key.ts

@@ -12,7 +12,12 @@ export function getPerplexityApiKeyFromEnv(): string {
         ? process.env
         : undefined
 
-  const key = env?.PERPLEXITY_API_KEY || env?.PPLX_API_KEY
+  const key = [env?.PERPLEXITY_API_KEY, env?.PPLX_API_KEY]
+    .find(
+      (value): value is string =>
+        typeof value === 'string' && value.trim().length > 0,
+    )
+    ?.trim()
 
   if (!key) {
     throw new Error(

packages/typescript/ai-perplexity/tests/chat-client.test.ts

@@ -24,6 +24,11 @@ describe('createPerplexityChatClient', () => {
     expect(client.apiKey).toBe('explicit')
   })
 
+  it('falls back to env when explicit apiKey is blank', () => {
+    const client = createPerplexityChatClient({ apiKey: '   ' })
+    expect(client.apiKey).toBe('test-key')
+  })
+
   it('falls back to PPLX_API_KEY when PERPLEXITY_API_KEY is not set', () => {
     delete process.env.PERPLEXITY_API_KEY
     process.env.PPLX_API_KEY = 'fallback'

packages/typescript/ai-perplexity/tests/search-client.test.ts

@@ -63,6 +63,19 @@ describe('PerplexitySearchClient', () => {
     })
   })
 
+  it('falls back to env when explicit apiKey is blank', async () => {
+    const fetchMock = makeFetchMock({ results: [] })
+    const client = new PerplexitySearchClient({
+      apiKey: '   ',
+      fetch: fetchMock as any,
+    })
+
+    await client.search({ query: 'q' })
+
+    const headers = fetchMock.mock.calls[0]![1].headers as Record<string, string>
+    expect(headers.Authorization).toBe('Bearer test-key')
+  })
+
   it('forwards optional filters in the request body', async () => {
     const fetchMock = makeFetchMock({ results: [] })
     const client = new PerplexitySearchClient({ fetch: fetchMock as any })
@@ -110,6 +123,36 @@ describe('PerplexitySearchClient', () => {
     ).rejects.toThrow(/non-empty `query`/i)
   })
 
+  it('throws when query is whitespace only', async () => {
+    const fetchMock = makeFetchMock({ results: [] })
+    const client = new PerplexitySearchClient({ fetch: fetchMock as any })
+    await expect(client.search({ query: '   ' })).rejects.toThrow(
+      /non-empty `query`/i,
+    )
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('trims query and clamps max_results before forwarding', async () => {
+    const fetchMock = makeFetchMock({ results: [] })
+    const client = new PerplexitySearchClient({ fetch: fetchMock as any })
+    await client.search({ query: '  mars rover  ', max_results: 99 })
+
+    const body = JSON.parse(fetchMock.mock.calls[0]![1].body as string)
+    expect(body).toEqual({
+      query: 'mars rover',
+      max_results: 20,
+    })
+  })
+
+  it('clamps max_results to the minimum before forwarding', async () => {
+    const fetchMock = makeFetchMock({ results: [] })
+    const client = new PerplexitySearchClient({ fetch: fetchMock as any })
+    await client.search({ query: 'q', max_results: 0 })
+
+    const body = JSON.parse(fetchMock.mock.calls[0]![1].body as string)
+    expect(body.max_results).toBe(1)
+  })
+
   it('falls back to PPLX_API_KEY when PERPLEXITY_API_KEY is not set', async () => {
     delete process.env.PERPLEXITY_API_KEY
     process.env.PPLX_API_KEY = 'fallback-key'
@@ -120,6 +163,16 @@ describe('PerplexitySearchClient', () => {
     expect(headers.Authorization).toBe('Bearer fallback-key')
   })
 
+  it('ignores whitespace-only PERPLEXITY_API_KEY when PPLX_API_KEY is set', async () => {
+    process.env.PERPLEXITY_API_KEY = '   '
+    process.env.PPLX_API_KEY = 'fallback-key'
+    const fetchMock = makeFetchMock({ results: [] })
+    const client = new PerplexitySearchClient({ fetch: fetchMock as any })
+    await client.search({ query: 'q' })
+    const headers = fetchMock.mock.calls[0]![1].headers as Record<string, string>
+    expect(headers.Authorization).toBe('Bearer fallback-key')
+  })
+
   it('throws if neither env var is set and no apiKey is passed', () => {
     delete process.env.PERPLEXITY_API_KEY
     delete process.env.PPLX_API_KEY

packages/typescript/ai-perplexity/tests/search-tool.test.ts

@@ -2,11 +2,18 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { perplexitySearchTool } from '../src/search/tool'
 
 describe('perplexitySearchTool', () => {
+  const ORIGINAL_PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY
+
   beforeEach(() => {
     process.env.PERPLEXITY_API_KEY = 'test-key'
   })
 
   afterEach(() => {
+    if (ORIGINAL_PERPLEXITY_API_KEY === undefined) {
+      delete process.env.PERPLEXITY_API_KEY
+    } else {
+      process.env.PERPLEXITY_API_KEY = ORIGINAL_PERPLEXITY_API_KEY
+    }
     vi.restoreAllMocks()
   })
 
@@ -101,6 +108,18 @@ describe('perplexitySearchTool', () => {
     })
   })
 
+  it('throws when defaultMaxResults is outside the allowed range', () => {
+    expect(() => perplexitySearchTool({ defaultMaxResults: 0 })).toThrow(
+      /integer between 1 and 20/i,
+    )
+    expect(() => perplexitySearchTool({ defaultMaxResults: 21 })).toThrow(
+      /integer between 1 and 20/i,
+    )
+    expect(() => perplexitySearchTool({ defaultMaxResults: 1.5 })).toThrow(
+      /integer between 1 and 20/i,
+    )
+  })
+
   it('honors custom name and description overrides', () => {
     const tool = perplexitySearchTool({
       apiKey: 'k',