@youdotcom-oss/api 0.1.1 → 0.2.1

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 },
+  )
+})

package/src/main.ts

@@ -10,13 +10,14 @@
 // Contents
 export * from './contents/contents.schemas.ts'
 export * from './contents/contents.utils.ts'
-// Express
-export * from './express/express.schemas.ts'
-export * from './express/express.utils.ts'
+// Deep-Search
+export * from './deep-search/deep-search.schemas.ts'
+export * from './deep-search/deep-search.utils.ts'
 // Search
 export * from './search/search.schemas.ts'
 export * from './search/search.utils.ts'
 // Shared
 export * from './shared/api.constants.ts'
 export * from './shared/api.types.ts'
+export * from './shared/dry-run-utils.ts'
 export * from './shared/generate-error-report-link.ts'

package/src/search/search.schemas.ts

@@ -1,7 +1,70 @@
 import * as z from 'zod'
 
+/**
+ * Language codes supported by You.com Search API (BCP 47 format)
+ * Based on OpenAPI spec: https://you.com/specs/openapi_search_v1.yaml
+ */
+export const LanguageSchema = z.enum([
+  'AR',
+  'EU',
+  'BN',
+  'BG',
+  'CA',
+  'ZH-HANS',
+  'ZH-HANT',
+  'HR',
+  'CS',
+  'DA',
+  'NL',
+  'EN',
+  'EN-GB',
+  'ET',
+  'FI',
+  'FR',
+  'GL',
+  'DE',
+  'EL',
+  'GU',
+  'HE',
+  'HI',
+  'HU',
+  'IS',
+  'IT',
+  'JP',
+  'KN',
+  'KO',
+  'LV',
+  'LT',
+  'MS',
+  'ML',
+  'MR',
+  'NB',
+  'PL',
+  'PT-BR',
+  'PT-PT',
+  'PA',
+  'RO',
+  'RU',
+  'SR',
+  'SK',
+  'SL',
+  'ES',
+  'SV',
+  'TA',
+  'TE',
+  'TH',
+  'TR',
+  'UK',
+  'VI',
+])
+
 export const SearchQuerySchema = z.object({
-  query: z.string().min(1, 'Query is required').describe('Search query (supports +, -, site:, filetype:, lang:)'),
+  query: z
+    .string()
+    .min(1, 'Query is required')
+    .describe(
+      'Search query. Supports operators: site:domain.com (domain filter), filetype:pdf (file type), +term (include), -term (exclude), AND/OR/NOT (boolean logic), lang:en (language). Example: "machine learning (Python OR PyTorch) -TensorFlow filetype:pdf"',
+    ),
   count: z.number().int().min(1).max(100).optional().describe('Max results per section'),
   freshness: z.string().optional().describe('day/week/month/year or YYYY-MM-DDtoYYYY-MM-DD'),
   offset: z.number().int().min(0).max(9).optional().describe('Pagination offset'),
@@ -32,6 +95,7 @@ export const SearchQuerySchema = z.object({
       'CN',
       'PL',
       'PT',
+      'PT-BR',
       'PH',
       'RU',
       'SA',
@@ -47,11 +111,6 @@ export const SearchQuerySchema = z.object({
     .optional()
     .describe('Country code'),
   safesearch: z.enum(['off', 'moderate', 'strict']).optional().describe('Filter level'),
-  site: z.string().optional().describe('Specific domain'),
-  fileType: z.string().optional().describe('File type'),
-  language: z.string().optional().describe('ISO 639-1 language code'),
-  excludeTerms: z.string().optional().describe('Terms to exclude (pipe-separated)'),
-  exactTerms: z.string().optional().describe('Exact terms (pipe-separated)'),
   livecrawl: z.enum(['web', 'news', 'all']).optional().describe('Live-crawl sections for full content'),
   livecrawl_formats: z.enum(['html', 'markdown']).optional().describe('Format for crawled content'),
 })

package/src/search/search.utils.ts

@@ -5,7 +5,7 @@ import { type SearchQuery, SearchResponseSchema } from './search.schemas.ts'
 
 export const fetchSearchResults = async ({
   YDC_API_KEY = process.env.YDC_API_KEY,
-  searchQuery: { query, site, fileType, language, exactTerms, excludeTerms, ...rest },
+  searchQuery,
   getUserAgent,
 }: {
   searchQuery: SearchQuery
@@ -16,33 +16,11 @@ export const fetchSearchResults = async ({
 
   const searchParams = new URLSearchParams()
 
-  // Build Query Param
-  const searchQuery = [query]
-  site && searchQuery.push(`site:${site}`)
-  fileType && searchQuery.push(`filetype:${fileType}`)
-  language && searchQuery.push(`lang:${language}`)
-  if (exactTerms && excludeTerms) {
-    throw new Error('Cannot specify both exactTerms and excludeTerms - please use only one')
-  }
-  exactTerms &&
-    searchQuery.push(
-      exactTerms
-        .split('|')
-        .map((term) => `+${term}`)
-        .join(' AND '),
-    )
-  excludeTerms &&
-    searchQuery.push(
-      excludeTerms
-        .split('|')
-        .map((term) => `-${term}`)
-        .join(' AND '),
-    )
-  searchParams.append('query', searchQuery.join(' '))
-
-  // Append additional advanced Params
-  for (const [name, value] of Object.entries(rest)) {
-    if (value) searchParams.append(name, `${value}`)
+  // Append all query parameters
+  for (const [name, value] of Object.entries(searchQuery)) {
+    if (value !== undefined && value !== null) {
+      searchParams.append(name, `${value}`)
+    }
   }
 
   url.search = searchParams.toString()

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

@@ -0,0 +1,122 @@
+import { describe, expect, test } from 'bun:test'
+import { SEARCH_API_URL } from '../../shared/api.constants.ts'
+import { buildSearchRequest } from '../../shared/dry-run-utils.ts'
+
+describe('buildSearchRequest', () => {
+  const getUserAgent = () => 'test-agent'
+  const YDC_API_KEY = 'test-key'
+
+  test('builds basic search request', () => {
+    const request = buildSearchRequest({
+      searchQuery: { query: 'AI' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.url).toBe(SEARCH_API_URL)
+    expect(request.method).toBe('GET')
+    expect(request.headers['X-API-Key']).toBe('test-key')
+    expect(request.headers['User-Agent']).toBe('test-agent')
+    expect(request.queryParams?.query).toBe('AI')
+  })
+
+  test('passes query with site: operator directly', () => {
+    const request = buildSearchRequest({
+      searchQuery: { query: 'AI site:you.com' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.queryParams?.query).toBe('AI site:you.com')
+  })
+
+  test('passes query with filetype: operator directly', () => {
+    const request = buildSearchRequest({
+      searchQuery: { query: 'tutorial filetype:pdf' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.queryParams?.query).toBe('tutorial filetype:pdf')
+  })
+
+  test('passes query with lang: operator directly', () => {
+    const request = buildSearchRequest({
+      searchQuery: { query: 'search lang:en' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.queryParams?.query).toBe('search lang:en')
+  })
+
+  test('passes query with +term inclusion operator directly', () => {
+    const request = buildSearchRequest({
+      searchQuery: { query: 'search +machine +learning' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.queryParams?.query).toBe('search +machine +learning')
+  })
+
+  test('passes query with -term exclusion operator directly', () => {
+    const request = buildSearchRequest({
+      searchQuery: { query: 'python -django -flask' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.queryParams?.query).toBe('python -django -flask')
+  })
+
+  test('passes query with boolean operators directly', () => {
+    const request = buildSearchRequest({
+      searchQuery: { query: '(Python OR JavaScript) AND tutorial -deprecated' },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.queryParams?.query).toBe('(Python OR JavaScript) AND tutorial -deprecated')
+  })
+
+  test('includes advanced search parameters', () => {
+    const request = buildSearchRequest({
+      searchQuery: {
+        query: 'AI',
+        count: 10,
+        freshness: 'week',
+        offset: 5,
+        country: 'US',
+        safesearch: 'moderate',
+        livecrawl: 'web',
+        livecrawl_formats: 'markdown',
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.queryParams?.query).toBe('AI')
+    expect(request.queryParams?.count).toBe('10')
+    expect(request.queryParams?.freshness).toBe('week')
+    expect(request.queryParams?.offset).toBe('5')
+    expect(request.queryParams?.country).toBe('US')
+    expect(request.queryParams?.safesearch).toBe('moderate')
+    expect(request.queryParams?.livecrawl).toBe('web')
+    expect(request.queryParams?.livecrawl_formats).toBe('markdown')
+  })
+
+  test('combines multiple operators in query string', () => {
+    const request = buildSearchRequest({
+      searchQuery: {
+        query: 'machine learning best practices (Python OR PyTorch) -TensorFlow filetype:pdf',
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.queryParams?.query).toBe(
+      'machine learning best practices (Python OR PyTorch) -TensorFlow filetype:pdf',
+    )
+  })
+})

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

@@ -0,0 +1,152 @@
+import { describe, expect, test } from 'bun:test'
+import { LanguageSchema, SearchQuerySchema } from '../search.schemas.ts'
+
+describe('SearchQuerySchema OpenAPI validation', () => {
+  test('accepts valid query parameters', () => {
+    const validQueries = [
+      { query: 'AI' },
+      { query: 'test', count: 10, freshness: 'week' },
+      { query: 'search', country: 'US', safesearch: 'moderate' },
+      { query: 'livecrawl test', livecrawl: 'web', livecrawl_formats: 'markdown' },
+    ]
+
+    for (const validQuery of validQueries) {
+      expect(() => SearchQuerySchema.parse(validQuery)).not.toThrow()
+    }
+  })
+
+  test('rejects invalid query parameters', () => {
+    const invalidQueries = [
+      {}, // Missing query
+      { query: '' }, // Empty query
+      { query: 'test', count: 0 }, // Count too low
+      { query: 'test', count: 101 }, // Count too high
+      { query: 'test', offset: -1 }, // Negative offset
+      { query: 'test', offset: 10 }, // Offset too high
+      { query: 'test', safesearch: 'invalid' }, // Invalid safesearch
+      { query: 'test', livecrawl: 'invalid' }, // Invalid livecrawl
+    ]
+
+    for (const invalidQuery of invalidQueries) {
+      expect(() => SearchQuerySchema.parse(invalidQuery)).toThrow()
+    }
+  })
+
+  test('LanguageSchema includes all 51 BCP 47 codes', () => {
+    // Test a sample of language codes from the OpenAPI spec
+    const languageCodes = [
+      'AR',
+      'EU',
+      'BN',
+      'BG',
+      'CA',
+      'ZH-HANS',
+      'ZH-HANT',
+      'HR',
+      'CS',
+      'DA',
+      'NL',
+      'EN',
+      'EN-GB',
+      'ET',
+      'FI',
+      'FR',
+      'GL',
+      'DE',
+      'EL',
+      'GU',
+      'HE',
+      'HI',
+      'HU',
+      'IS',
+      'IT',
+      'JP',
+      'KN',
+      'KO',
+      'LV',
+      'LT',
+      'MS',
+      'ML',
+      'MR',
+      'NB',
+      'PL',
+      'PT-BR',
+      'PT-PT',
+      'PA',
+      'RO',
+      'RU',
+      'SR',
+      'SK',
+      'SL',
+      'ES',
+      'SV',
+      'TA',
+      'TE',
+      'TH',
+      'TR',
+      'UK',
+      'VI',
+    ]
+
+    for (const code of languageCodes) {
+      expect(() => LanguageSchema.parse(code)).not.toThrow()
+    }
+
+    // Test that the schema has exactly 51 values
+    expect(LanguageSchema.options.length).toBe(51)
+  })
+
+  test('rejects invalid language codes', () => {
+    const invalidCodes = ['XX', 'INVALID', 'en', 'zh', '123']
+
+    for (const code of invalidCodes) {
+      expect(() => LanguageSchema.parse(code)).toThrow()
+    }
+  })
+
+  test('accepts all country codes from OpenAPI spec', () => {
+    const countryCodes = [
+      'AR',
+      'AU',
+      'AT',
+      'BE',
+      'BR',
+      'CA',
+      'CL',
+      'DK',
+      'FI',
+      'FR',
+      'DE',
+      'HK',
+      'IN',
+      'ID',
+      'IT',
+      'JP',
+      'KR',
+      'MY',
+      'MX',
+      'NL',
+      'NZ',
+      'NO',
+      'CN',
+      'PL',
+      'PT',
+      'PT-BR',
+      'PH',
+      'RU',
+      'SA',
+      'ZA',
+      'ES',
+      'SE',
+      'CH',
+      'TW',
+      'TR',
+      'GB',
+      'US',
+    ]
+
+    for (const code of countryCodes) {
+      expect(() => SearchQuerySchema.parse({ query: 'test', country: code })).not.toThrow()
+    }
+  })
+})

package/src/search/tests/{search.utils.spec.ts → search.utils.docker.ts}

@@ -15,9 +15,7 @@ describe('fetchSearchResults', () => {
       expect(result).toHaveProperty('results')
       expect(result).toHaveProperty('metadata')
       expect(result.results).toHaveProperty('web')
-      // expect(result.results).toHaveProperty('news');
       expect(Array.isArray(result.results.web)).toBe(true)
-      // expect(Array.isArray(result.results.news)).toBe(true);
 
       // Assert required metadata fields
       expect(typeof result.metadata?.query).toBe('string')
@@ -57,7 +55,6 @@ describe('fetchSearchResults', () => {
       })
 
       // Test that web results have required properties
-      // biome-ignore lint/style/noNonNullAssertion: Test
       const webResult = result.results.web![0]
 
       expect(webResult).toHaveProperty('url')
@@ -65,13 +62,6 @@ describe('fetchSearchResults', () => {
       expect(webResult).toHaveProperty('description')
       expect(webResult).toHaveProperty('snippets')
       expect(Array.isArray(webResult?.snippets)).toBe(true)
-
-      // Test that news results have required properties
-      // const newsResult = result.results.news![0];
-      // expect(newsResult).toHaveProperty('url');
-      // expect(newsResult).toHaveProperty('title');
-      // expect(newsResult).toHaveProperty('description');
-      // expect(newsResult).toHaveProperty('page_age');
     },
     { retry: 2 },
   )

package/src/shared/api.constants.ts

@@ -6,5 +6,5 @@
  */
 
 export const SEARCH_API_URL = 'https://ydc-index.io/v1/search'
-export const EXPRESS_API_URL = 'https://api.you.com/v1/agents/runs'
+export const DEEP_SEARCH_API_URL = 'https://api.you.com/v1/deep_search'
 export const CONTENTS_API_URL = 'https://ydc-index.io/v1/contents'

package/src/shared/check-response-for-errors.ts

@@ -1,7 +1,7 @@
 /**
  * Checks if a response object contains an error field and throws if found
  * Handles API responses that return 200 status but contain error messages
- * Used by both search and express agent utilities
+ * Used by search, deep-search, and contents utilities
  */
 export const checkResponseForErrors = (responseData: unknown) => {
   if (typeof responseData === 'object' && responseData !== null && 'error' in responseData) {