@youdotcom-oss/api 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "You.com API client with bundled CLI for agents supporting Agent Skills",
   "license": "MIT",
   "engines": {
@@ -63,6 +63,6 @@
     "test:watch": "bun test --watch"
   },
   "dependencies": {
-    "zod": "^4.3.5"
+    "zod": "^4.3.6"
   }
 }

package/src/cli.ts

@@ -4,7 +4,7 @@
  *
  * Commands:
  *   search <query>              - Search the web with You.com
- *   express <input>             - Get AI answers with web context
+ *   deep-search <query>         - Perform deep research with comprehensive answers
  *   contents <url> [url...]     - Extract content from URLs
  *
  * Options:
@@ -14,10 +14,17 @@
  *   --help, -h                  - Show help
  */
 import { parseArgs } from 'node:util'
+import type * as z from 'zod'
 import packageJson from '../package.json' with { type: 'json' }
-import { contentsCommand } from './commands/contents.ts'
-import { expressCommand } from './commands/express.ts'
-import { searchCommand } from './commands/search.ts'
+import { ContentsQuerySchema } from './contents/contents.schemas.ts'
+import { fetchContents } from './contents/contents.utils.ts'
+import { DeepSearchQuerySchema } from './deep-search/deep-search.schemas.ts'
+import { callDeepSearch } from './deep-search/deep-search.utils.ts'
+import { SearchQuerySchema } from './search/search.schemas.ts'
+import { fetchSearchResults } from './search/search.utils.ts'
+import type { GetUserAgent } from './shared/api.types.ts'
+import { type CommandConfig, runCommand } from './shared/command-runner.ts'
+import { buildContentsRequest, buildDeepSearchRequest, buildSearchRequest } from './shared/dry-run-utils.ts'
 import { generateErrorReportLink } from './shared/generate-error-report-link.ts'
 import { useGetUserAgent } from './shared/use-get-user-agents.ts'
 
@@ -35,7 +42,7 @@ Usage: ydc <command> --json <json> [options]
 
 Commands:
   search                      Search the web with You.com
-  express                     Get AI answers with web context
+  deep-search                 Perform deep research with comprehensive answers
   contents                    Extract content from URLs
 
 Global Options:
@@ -43,6 +50,7 @@ Global Options:
   --api-key <key>             You.com API key (overrides YDC_API_KEY)
   --client <name>             Client name for tracking and debugging
   --schema                    Output JSON schema for what can be passed to --json
+  --dry-run                   Show request details without making API call
   --help, -h                  Show this help
 
 Environment Variables:
@@ -55,9 +63,10 @@ Output Format:
 
 Examples:
   ydc search --json '{"query":"AI developments"}' --client Openclaw
-  ydc express --json '{"input":"What happened today?","tools":[{"type":"web_search"}]}' --client MyAgent
+  ydc deep-search --json '{"query":"What are the latest breakthroughs in AI?","search_effort":"high"}' --client MyAgent
   ydc contents --json '{"urls":["https://example.com"],"formats":["markdown"]}'
   ydc search --schema  # Get JSON schema for search --json input
+  ydc search --json '{"query":"AI"}' --dry-run  # Inspect request without API call
   ydc search --json '{"query":"AI"}' | jq '.data.results.web[0].title'
 
 More info: https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/api
@@ -65,22 +74,84 @@ More info: https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/api
   process.exit(command ? 0 : 2)
 }
 
+// Command configuration map
+const commands = {
+  search: {
+    schema: SearchQuerySchema,
+    handler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent,
+    }: {
+      input: z.infer<typeof SearchQuerySchema>
+      YDC_API_KEY: string
+      getUserAgent: GetUserAgent
+    }) => fetchSearchResults({ searchQuery: input, YDC_API_KEY, getUserAgent }),
+    dryRunHandler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent,
+    }: {
+      input: z.infer<typeof SearchQuerySchema>
+      YDC_API_KEY: string
+      getUserAgent: GetUserAgent
+    }) => buildSearchRequest({ searchQuery: input, YDC_API_KEY, getUserAgent }),
+  },
+  'deep-search': {
+    schema: DeepSearchQuerySchema,
+    handler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent,
+    }: {
+      input: z.infer<typeof DeepSearchQuerySchema>
+      YDC_API_KEY: string
+      getUserAgent: GetUserAgent
+    }) => callDeepSearch({ deepSearchQuery: input, YDC_API_KEY, getUserAgent }),
+    dryRunHandler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent,
+    }: {
+      input: z.infer<typeof DeepSearchQuerySchema>
+      YDC_API_KEY: string
+      getUserAgent: GetUserAgent
+    }) => buildDeepSearchRequest({ deepSearchQuery: input, YDC_API_KEY, getUserAgent }),
+  },
+  contents: {
+    schema: ContentsQuerySchema,
+    handler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent,
+    }: {
+      input: z.infer<typeof ContentsQuerySchema>
+      YDC_API_KEY: string
+      getUserAgent: GetUserAgent
+    }) => fetchContents({ contentsQuery: input, YDC_API_KEY, getUserAgent }),
+    dryRunHandler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent,
+    }: {
+      input: z.infer<typeof ContentsQuerySchema>
+      YDC_API_KEY: string
+      getUserAgent: GetUserAgent
+    }) => buildContentsRequest({ contentsQuery: input, YDC_API_KEY, getUserAgent }),
+  },
+}
+
+// Validate command
+if (!(command in commands)) {
+  console.error(`Unknown command: ${command}`)
+  console.error(`Run 'ydc --help' for usage`)
+  process.exit(2)
+}
+
+// Execute command
 try {
-  switch (command) {
-    case 'search':
-      await searchCommand(args)
-      break
-    case 'express':
-      await expressCommand(args)
-      break
-    case 'contents':
-      await contentsCommand(args)
-      break
-    default:
-      console.error(`Unknown command: ${command}`)
-      console.error(`Run 'ydc --help' for usage`)
-      process.exit(2)
-  }
+  // Type assertion is safe because we validated command exists above
+  await runCommand(args, commands[command as keyof typeof commands] as CommandConfig<unknown, unknown>)
   process.exit(0)
 } catch (error) {
   console.error(error)

package/src/contents/contents.schemas.ts

@@ -21,20 +21,21 @@ export type ContentsQuery = z.infer<typeof ContentsQuerySchema>
 
 /**
  * Schema for a single content item in the API response
+ * Based on OpenAPI spec: https://you.com/specs/openapi_contents.yaml
  */
 const ContentsItemSchema = z.object({
   url: z.string().describe('URL'),
-  title: z.string().optional().describe('Title'),
-  html: z.string().optional().describe('HTML content'),
-  markdown: z.string().optional().describe('Markdown content'),
+  title: z.string().optional().describe('Title (optional in actual API responses)'),
+  html: z.string().nullable().optional().describe('HTML content'),
+  markdown: z.string().nullable().optional().describe('Markdown content'),
   metadata: z
     .object({
-      jsonld: z.array(z.record(z.string(), z.unknown())).optional().describe('JSON-LD structured data (Schema.org)'),
-      opengraph: z.record(z.string(), z.string()).optional().describe('OpenGraph meta tags'),
-      twitter: z.record(z.string(), z.string()).optional().describe('Twitter Card metadata'),
+      site_name: z.string().nullable().optional().describe('OpenGraph site name'),
+      favicon_url: z.string().describe('Favicon URL'),
     })
+    .nullable()
     .optional()
-    .describe('Structured metadata when available'),
+    .describe('Page metadata (only when metadata format requested)'),
 })
 
 /**

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

@@ -0,0 +1,109 @@
+import { describe, expect, test } from 'bun:test'
+import { CONTENTS_API_URL } from '../../shared/api.constants.ts'
+import { buildContentsRequest } from '../../shared/dry-run-utils.ts'
+
+describe('buildContentsRequest', () => {
+  const getUserAgent = () => 'test-agent'
+  const YDC_API_KEY = 'test-key'
+
+  test('builds basic contents request with markdown format', () => {
+    const request = buildContentsRequest({
+      contentsQuery: { urls: ['https://example.com'] },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    expect(request.url).toBe(CONTENTS_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.urls).toEqual(['https://example.com'])
+    expect(body.formats).toEqual(['markdown'])
+  })
+
+  test('builds request with multiple URLs', () => {
+    const request = buildContentsRequest({
+      contentsQuery: {
+        urls: ['https://a.com', 'https://b.com', 'https://c.com'],
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.urls).toEqual(['https://a.com', 'https://b.com', 'https://c.com'])
+  })
+
+  test('builds request with multiple formats', () => {
+    const request = buildContentsRequest({
+      contentsQuery: {
+        urls: ['https://example.com'],
+        formats: ['html', 'markdown', 'metadata'],
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.formats).toEqual(['html', 'markdown', 'metadata'])
+  })
+
+  test('builds request with deprecated format parameter', () => {
+    const request = buildContentsRequest({
+      contentsQuery: {
+        urls: ['https://example.com'],
+        format: 'html',
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.formats).toEqual(['html'])
+  })
+
+  test('prefers formats array over deprecated format parameter', () => {
+    const request = buildContentsRequest({
+      contentsQuery: {
+        urls: ['https://example.com'],
+        formats: ['markdown', 'metadata'],
+        format: 'html',
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.formats).toEqual(['markdown', 'metadata'])
+  })
+
+  test('includes crawl_timeout when provided', () => {
+    const request = buildContentsRequest({
+      contentsQuery: {
+        urls: ['https://example.com'],
+        crawl_timeout: 30,
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.crawl_timeout).toBe(30)
+  })
+
+  test('omits crawl_timeout when not provided', () => {
+    const request = buildContentsRequest({
+      contentsQuery: {
+        urls: ['https://example.com'],
+      },
+      YDC_API_KEY,
+      getUserAgent,
+    })
+
+    const body = JSON.parse(request.body!)
+    expect(body.crawl_timeout).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test'
+import { ContentsQuerySchema } from '../contents.schemas.ts'
+
+describe('ContentsQuerySchema OpenAPI validation', () => {
+  test('accepts valid contents queries', () => {
+    const validQueries = [
+      { urls: ['https://example.com'] },
+      { urls: ['https://example.com'], formats: ['markdown'] },
+      { urls: ['https://example.com'], formats: ['html', 'markdown'] },
+      { urls: ['https://example.com'], formats: ['markdown', 'metadata'] },
+      { urls: ['https://example.com'], formats: ['html', 'markdown', 'metadata'] },
+      { urls: ['https://example.com'], format: 'html' }, // Deprecated but still supported
+      { urls: ['https://example.com'], crawl_timeout: 30 },
+      { urls: ['https://a.com', 'https://b.com', 'https://c.com'], formats: ['markdown'] },
+    ]
+
+    for (const validQuery of validQueries) {
+      expect(() => ContentsQuerySchema.parse(validQuery)).not.toThrow()
+    }
+  })
+
+  test('rejects invalid contents queries', () => {
+    const invalidQueries = [
+      {}, // Missing urls
+      { urls: [] }, // Empty urls array
+      { urls: ['not-a-url'] }, // Invalid URL
+      { urls: ['https://example.com'], formats: ['invalid'] }, // Invalid format
+      { urls: ['https://example.com'], crawl_timeout: 0 }, // Timeout too low
+      { urls: ['https://example.com'], crawl_timeout: 61 }, // Timeout too high
+    ]
+
+    for (const invalidQuery of invalidQueries) {
+      expect(() => ContentsQuerySchema.parse(invalidQuery)).toThrow()
+    }
+  })
+
+  test('accepts metadata format', () => {
+    const query = {
+      urls: ['https://example.com'],
+      formats: ['metadata'],
+    }
+
+    expect(() => ContentsQuerySchema.parse(query)).not.toThrow()
+  })
+
+  test('accepts all format combinations', () => {
+    const formatCombinations = [
+      ['html'],
+      ['markdown'],
+      ['metadata'],
+      ['html', 'markdown'],
+      ['html', 'metadata'],
+      ['markdown', 'metadata'],
+      ['html', 'markdown', 'metadata'],
+    ]
+
+    for (const formats of formatCombinations) {
+      expect(() => ContentsQuerySchema.parse({ urls: ['https://example.com'], formats })).not.toThrow()
+    }
+  })
+
+  test('crawl_timeout validation', () => {
+    // Valid timeouts (1-60)
+    const validTimeouts = [1, 30, 60]
+    for (const timeout of validTimeouts) {
+      expect(() => ContentsQuerySchema.parse({ urls: ['https://example.com'], crawl_timeout: timeout })).not.toThrow()
+    }
+
+    // Invalid timeouts
+    const invalidTimeouts = [0, -1, 61, 100]
+    for (const timeout of invalidTimeouts) {
+      expect(() => ContentsQuerySchema.parse({ urls: ['https://example.com'], crawl_timeout: timeout })).toThrow()
+    }
+  })
+})

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

@@ -0,0 +1,48 @@
+import * as z from 'zod'
+
+/**
+ * Search effort levels for deep-search API
+ * Controls computation budget and response time
+ */
+export const SearchEffortSchema = z.enum(['low', 'medium', 'high']).describe('Search effort level')
+
+/**
+ * Input schema for deep-search API
+ * Based on OpenAPI spec: https://docs.you.com/api-reference/deep-search/v1-deep_search
+ *
+ * @public
+ */
+export const DeepSearchQuerySchema = z.object({
+  query: z
+    .string()
+    .min(1, 'Query is required')
+    .describe('The research question or complex query requiring in-depth investigation and multi-step reasoning'),
+  search_effort: SearchEffortSchema.optional()
+    .default('medium')
+    .describe('Computation budget: low (<30s), medium (<60s, default), high (<300s)'),
+})
+
+export type DeepSearchQuery = z.infer<typeof DeepSearchQuerySchema>
+
+/**
+ * Schema for a single source in the deep-search response
+ *
+ * @public
+ */
+const DeepSearchSourceSchema = z.object({
+  url: z.string().describe('Source webpage URL'),
+  title: z.string().describe('Source webpage title'),
+  snippets: z.array(z.string()).describe('Relevant excerpts from the source page used in generating the answer'),
+})
+
+/**
+ * Response schema for deep-search API
+ *
+ * @public
+ */
+export const DeepSearchResponseSchema = z.object({
+  answer: z.string().describe('Comprehensive response with inline citations, formatted in Markdown'),
+  results: z.array(DeepSearchSourceSchema).describe('List of web sources used to generate the answer'),
+})
+
+export type DeepSearchResponse = z.infer<typeof DeepSearchResponseSchema>

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

@@ -0,0 +1,75 @@
+import type * as z from 'zod'
+import { DEEP_SEARCH_API_URL } from '../shared/api.constants.ts'
+import type { GetUserAgent } from '../shared/api.types.ts'
+import { checkResponseForErrors } from '../shared/check-response-for-errors.ts'
+import { type DeepSearchQuery, DeepSearchResponseSchema } from './deep-search.schemas.ts'
+
+/**
+ * Perform deep research using You.com Deep Search API
+ *
+ * @param params - Deep search query parameters
+ * @returns Deep search response with comprehensive answer and sources
+ *
+ * @public
+ */
+export const callDeepSearch = async ({
+  deepSearchQuery,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  deepSearchQuery: DeepSearchQuery
+  YDC_API_KEY: string
+  getUserAgent: GetUserAgent
+}) => {
+  const response = await fetch(DEEP_SEARCH_API_URL, {
+    method: 'POST',
+    headers: new Headers({
+      'X-API-Key': YDC_API_KEY || '',
+      'Content-Type': 'application/json',
+      'User-Agent': getUserAgent(),
+    }),
+    body: JSON.stringify(deepSearchQuery),
+  })
+
+  await checkResponseForErrors(response)
+  const data = await response.json()
+
+  return DeepSearchResponseSchema.parse(data)
+}
+
+/**
+ * Format deep-search response for display
+ * Returns markdown-formatted text with answer and sources
+ *
+ * @param response - Deep search API response
+ * @returns Formatted markdown string
+ *
+ * @public
+ */
+export const formatDeepSearchResponse = (response: z.infer<typeof DeepSearchResponseSchema>): string => {
+  const parts: string[] = []
+
+  // Add the comprehensive answer
+  parts.push('# Answer\n')
+  parts.push(response.answer)
+  parts.push('\n')
+
+  // Add sources section
+  if (response.results && response.results.length > 0) {
+    parts.push('\n## Sources\n')
+
+    for (const [index, source] of response.results.entries()) {
+      parts.push(`\n### ${index + 1}. ${source.title}\n`)
+      parts.push(`**URL:** ${source.url}\n`)
+
+      if (source.snippets && source.snippets.length > 0) {
+        parts.push('\n**Key Excerpts:**\n')
+        for (const snippet of source.snippets) {
+          parts.push(`> ${snippet}\n`)
+        }
+      }
+    }
+  }
+
+  return parts.join('\n')
+}

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()