@youdotcom-oss/api 0.2.0 → 0.2.1

package/bin/cli.js

@@ -15,7 +15,7 @@ import { parseArgs as parseArgs2 } from "node:util";
 // package.json
 var package_default = {
   name: "@youdotcom-oss/api",
-  version: "0.2.0",
+  version: "0.2.1",
   description: "You.com API client with bundled CLI for agents supporting Agent Skills",
   license: "MIT",
   engines: {
@@ -4856,13 +4856,16 @@ var DeepSearchResponseSchema = object({
 // src/deep-search/deep-search.utils.ts
 var callDeepSearch = async ({
   deepSearchQuery,
-  YDC_API_KEY,
+  YDC_API_KEY = process.env.YDC_API_KEY,
   getUserAgent
 }) => {
+  if (!YDC_API_KEY) {
+    throw new Error("YDC_API_KEY is required for Deep Search API");
+  }
   const response = await fetch(DEEP_SEARCH_API_URL, {
     method: "POST",
     headers: new Headers({
-      "X-API-Key": YDC_API_KEY || "",
+      "X-API-Key": YDC_API_KEY,
       "Content-Type": "application/json",
       "User-Agent": getUserAgent()
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/api",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "You.com API client with bundled CLI for agents supporting Agent Skills",
   "license": "MIT",
   "engines": {

package/src/deep-search/deep-search.utils.ts

@@ -14,17 +14,21 @@ import { type DeepSearchQuery, DeepSearchResponseSchema } from './deep-search.sc
  */
 export const callDeepSearch = async ({
   deepSearchQuery,
-  YDC_API_KEY,
+  YDC_API_KEY = process.env.YDC_API_KEY,
   getUserAgent,
 }: {
   deepSearchQuery: DeepSearchQuery
-  YDC_API_KEY: string
+  YDC_API_KEY?: string
   getUserAgent: GetUserAgent
 }) => {
+  if (!YDC_API_KEY) {
+    throw new Error('YDC_API_KEY is required for Deep Search API')
+  }
+
   const response = await fetch(DEEP_SEARCH_API_URL, {
     method: 'POST',
     headers: new Headers({
-      'X-API-Key': YDC_API_KEY || '',
+      'X-API-Key': YDC_API_KEY,
       'Content-Type': 'application/json',
       'User-Agent': getUserAgent(),
     }),

package/src/deep-search/tests/deep-search.request.spec.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from 'bun:test'
+import { DEEP_SEARCH_API_URL } from '../../shared/api.constants.ts'
+import { buildDeepSearchRequest } from '../../shared/dry-run-utils.ts'
+
+describe('buildDeepSearchRequest', () => {
+  const getUserAgent = () => 'test-agent'
+  const YDC_API_KEY = 'test-key'
+
+  test('builds basic deep-search request with query only', () => {
+    const request = buildDeepSearchRequest({
+      deepSearchQuery: { query: 'What is AI?' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.url).toBe(DEEP_SEARCH_API_URL)
+    expect(request.method).toBe('POST')
+    expect(request.headers['X-API-Key']).toBe('test-key')
+    expect(request.headers['Content-Type']).toBe('application/json')
+    expect(request.headers['User-Agent']).toBe('test-agent')
+
+    const body = JSON.parse(request.body!)
+    expect(body.query).toBe('What is AI?')
+    // search_effort not in body when not provided (default applied by schema validation, not dry-run)
+    expect(body.search_effort).toBeUndefined()
+  })
+
+  test('builds request with explicit medium search effort', () => {
+    const request = buildDeepSearchRequest({
+      deepSearchQuery: { query: 'What is AI?', search_effort: 'medium' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.query).toBe('What is AI?')
+    expect(body.search_effort).toBe('medium')
+  })
+
+  test('builds request with low search effort', () => {
+    const request = buildDeepSearchRequest({
+      deepSearchQuery: {
+        query: 'Quick explanation of JWT',
+        search_effort: 'low',
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.query).toBe('Quick explanation of JWT')
+    expect(body.search_effort).toBe('low')
+  })
+
+  test('builds request with high search effort', () => {
+    const request = buildDeepSearchRequest({
+      deepSearchQuery: {
+        query: 'Comprehensive analysis of climate change impacts',
+        search_effort: 'high',
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.query).toBe('Comprehensive analysis of climate change impacts')
+    expect(body.search_effort).toBe('high')
+  })
+
+  test('builds request with complex research question', () => {
+    const complexQuery = `What are the key differences between microservices and monolithic architecture?
+Include pros and cons of each approach, best use cases, and migration strategies.`
+
+    const request = buildDeepSearchRequest({
+      deepSearchQuery: {
+        query: complexQuery,
+        search_effort: 'high',
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.query).toBe(complexQuery)
+    expect(body.search_effort).toBe('high')
+  })
+
+  test('uses correct API URL', () => {
+    const request = buildDeepSearchRequest({
+      deepSearchQuery: { query: 'test' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.url).toBe('https://api.you.com/v1/deep_search')
+  })
+
+  test('includes all required headers', () => {
+    const request = buildDeepSearchRequest({
+      deepSearchQuery: { query: 'test' },
+      YDC_API_KEY: 'my-api-key',
+      getUserAgent: () => 'CustomAgent/1.0',
+    })
+
+    expect(request.headers['X-API-Key']).toBe('my-api-key')
+    expect(request.headers['Content-Type']).toBe('application/json')
+    expect(request.headers['User-Agent']).toBe('CustomAgent/1.0')
+  })
+})

package/src/deep-search/tests/deep-search.schema-validation.spec.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from 'bun:test'
+import { DeepSearchQuerySchema, SearchEffortSchema } from '../deep-search.schemas.ts'
+
+describe('DeepSearchQuerySchema OpenAPI validation', () => {
+  test('accepts valid query parameters', () => {
+    const validQueries = [
+      { query: 'What is quantum computing?' },
+      { query: 'Explain machine learning', search_effort: 'low' },
+      { query: 'Latest AI developments', search_effort: 'medium' },
+      { query: 'Comprehensive research on climate change', search_effort: 'high' },
+    ]
+
+    for (const validQuery of validQueries) {
+      expect(() => DeepSearchQuerySchema.parse(validQuery)).not.toThrow()
+    }
+  })
+
+  test('rejects invalid query parameters', () => {
+    const invalidQueries = [
+      {}, // Missing query
+      { query: '' }, // Empty query
+      { query: 'test', search_effort: 'invalid' }, // Invalid search_effort
+      { query: 'test', search_effort: 'extreme' }, // Invalid effort level
+    ]
+
+    for (const invalidQuery of invalidQueries) {
+      expect(() => DeepSearchQuerySchema.parse(invalidQuery)).toThrow()
+    }
+  })
+
+  test('defaults search_effort to medium when not provided', () => {
+    const result = DeepSearchQuerySchema.parse({ query: 'test query' })
+    expect(result.search_effort).toBe('medium')
+  })
+
+  test('SearchEffortSchema accepts all valid effort levels', () => {
+    const validEfforts = ['low', 'medium', 'high']
+
+    for (const effort of validEfforts) {
+      expect(() => SearchEffortSchema.parse(effort)).not.toThrow()
+    }
+  })
+
+  test('SearchEffortSchema rejects invalid effort levels', () => {
+    const invalidEfforts = ['none', 'extreme', 'ultra', 'minimal', '']
+
+    for (const effort of invalidEfforts) {
+      expect(() => SearchEffortSchema.parse(effort)).toThrow()
+    }
+  })
+
+  test('accepts complex research questions', () => {
+    const complexQueries = [
+      {
+        query: 'What are the key differences between REST and GraphQL APIs, and when should each be used?',
+        search_effort: 'high',
+      },
+      {
+        query: 'Compare the advantages and disadvantages of microservices architecture versus monolithic architecture',
+      },
+      {
+        query: 'What happened in AI research during 2024? Provide a comprehensive summary with key breakthroughs.',
+        search_effort: 'high',
+      },
+    ]
+
+    for (const query of complexQueries) {
+      expect(() => DeepSearchQuerySchema.parse(query)).not.toThrow()
+    }
+  })
+})

package/src/deep-search/tests/deep-search.utils.docker.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from 'bun:test'
+import { callDeepSearch } from '../deep-search.utils.ts'
+
+const getUserAgent = () => 'API/test (You.com;TEST)'
+
+describe('callDeepSearch', () => {
+  test(
+    'returns valid response structure for basic query',
+    async () => {
+      const result = await callDeepSearch({
+        deepSearchQuery: {
+          query: 'What is TypeScript?',
+          search_effort: 'low',
+        },
+        getUserAgent,
+      })
+
+      expect(result).toHaveProperty('answer')
+      expect(result).toHaveProperty('results')
+      expect(typeof result.answer).toBe('string')
+      expect(Array.isArray(result.results)).toBe(true)
+      expect(result.answer.length).toBeGreaterThan(0)
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'handles medium search effort',
+    async () => {
+      const result = await callDeepSearch({
+        deepSearchQuery: {
+          query: 'Explain REST API principles',
+          search_effort: 'medium',
+        },
+        getUserAgent,
+      })
+
+      expect(result).toHaveProperty('answer')
+      expect(result).toHaveProperty('results')
+      expect(typeof result.answer).toBe('string')
+      expect(Array.isArray(result.results)).toBe(true)
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'validates response schema with sources',
+    async () => {
+      const result = await callDeepSearch({
+        deepSearchQuery: {
+          query: 'What are the benefits of microservices?',
+          search_effort: 'low',
+        },
+        getUserAgent,
+      })
+
+      // Test that results have required properties
+      expect(result.results.length).toBeGreaterThan(0)
+
+      const source = result.results[0]
+      expect(source).toBeDefined()
+      expect(source).toHaveProperty('url')
+      expect(source).toHaveProperty('title')
+      expect(source).toHaveProperty('snippets')
+      expect(typeof source?.url).toBe('string')
+      expect(typeof source?.title).toBe('string')
+      expect(Array.isArray(source?.snippets)).toBe(true)
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'answer contains markdown with inline citations',
+    async () => {
+      const result = await callDeepSearch({
+        deepSearchQuery: {
+          query: 'What is JWT authentication?',
+          search_effort: 'low',
+        },
+        getUserAgent,
+      })
+
+      // Answer should be non-empty markdown string
+      expect(typeof result.answer).toBe('string')
+      expect(result.answer.length).toBeGreaterThan(0)
+
+      // Answer typically contains citations in the format [1], [2], etc.
+      // This is a soft check - citations may or may not be present
+      if (result.answer.includes('[')) {
+        expect(result.answer).toMatch(/\[\d+\]/)
+      }
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'handles complex multi-part questions',
+    async () => {
+      const result = await callDeepSearch({
+        deepSearchQuery: {
+          query: 'What is GraphQL and how does it differ from REST?',
+          search_effort: 'low',
+        },
+        getUserAgent,
+      })
+
+      expect(result).toHaveProperty('answer')
+      expect(result).toHaveProperty('results')
+      expect(result.results.length).toBeGreaterThan(0)
+
+      // Complex questions should have substantial answers
+      expect(result.answer.length).toBeGreaterThan(100)
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'sources include relevant snippets',
+    async () => {
+      const result = await callDeepSearch({
+        deepSearchQuery: {
+          query: 'What is Docker containerization?',
+          search_effort: 'low',
+        },
+        getUserAgent,
+      })
+
+      // Check that at least one source has snippets
+      const sourcesWithSnippets = result.results.filter((source) => source.snippets.length > 0)
+      expect(sourcesWithSnippets.length).toBeGreaterThan(0)
+
+      // Snippets should be non-empty strings
+      const firstSource = sourcesWithSnippets[0]
+      expect(firstSource).toBeDefined()
+      expect(firstSource?.snippets[0]?.length).toBeGreaterThan(0)
+    },
+    { retry: 2 },
+  )
+})