@youdotcom-oss/api 0.2.0 → 0.2.2

package/README.md

@@ -19,11 +19,11 @@ Fast, lightweight API client and CLI tools for web search, AI answers, and conte
 
 ```bash
 # Use with bunx (no install needed) - Schema-driven JSON input
-bunx @youdotcom-oss/api search --json '{"query":"AI developments"}' --client Openclaw
+bunx @youdotcom-oss/api search --json '{"query":"AI developments"}' --client ClaudeCode
 
 # Or install globally to use 'ydc' command
 bun i -g @youdotcom-oss/api
-ydc search --json '{"query":"AI developments"}' --client Openclaw
+ydc search --json '{"query":"AI developments"}' --client ClaudeCode
 
 # Get comprehensive research with citations
 bunx @youdotcom-oss/api deep-search --json '{
@@ -137,14 +137,14 @@ ydc search --json '{"query":"..."}' [options]
 
 Examples:
   # Basic search
-  ydc search --json '{"query":"machine learning"}' --client Openclaw
+  ydc search --json '{"query":"machine learning"}' --client ClaudeCode
 
   # Search with livecrawl (KEY FEATURE)
   ydc search --json '{
     "query":"documentation",
     "livecrawl":"web",
     "livecrawl_formats":"markdown"
-  }' --client Openclaw
+  }' --client ClaudeCode
 
   # Advanced filters
   ydc search --json '{
@@ -153,10 +153,10 @@ Examples:
     "fileType":"pdf",
     "freshness":"month",
     "count":10
-  }' --client Openclaw
+  }' --client ClaudeCode
 
   # Parse with jq
-  api search --json '{"query":"AI"}' --client Openclaw | \
+  api search --json '{"query":"AI"}' --client ClaudeCode | \
     jq -r '.results.web[] | .title'
 
   # Extract livecrawl content
@@ -164,7 +164,7 @@ Examples:
     "query":"docs",
     "livecrawl":"web",
     "livecrawl_formats":"markdown"
-  }' --client Openclaw | \
+  }' --client ClaudeCode | \
     jq -r '.results.web[0].contents.markdown'
 ```
 
@@ -190,18 +190,18 @@ ydc deep-search --json '{"query":"..."}' [options]
 
 Examples:
   # Comprehensive research with medium effort
-  api deep-search --json '{"query":"What is quantum computing?"}' --client Openclaw
+  api deep-search --json '{"query":"What is quantum computing?"}' --client ClaudeCode
 
   # High-effort deep research (up to 5 minutes)
   api deep-search --json '{
     "query":"Latest breakthroughs in AI agents",
     "search_effort":"high"
-  }' --client Openclaw
+  }' --client ClaudeCode
 
   # Parse answer and sources
   api deep-search --json '{
     "query":"AI trends 2026"
-  }' --client Openclaw | \
+  }' --client ClaudeCode | \
     jq -r '.answer, "\nSources:", (.results[]? | "- \(.title): \(.url)")'
 ```
 
@@ -219,25 +219,25 @@ Examples:
   api contents --json '{
     "urls":["https://example.com"],
     "formats":["markdown"]
-  }' --client Openclaw
+  }' --client ClaudeCode
 
   # Multiple formats
   api contents --json '{
     "urls":["https://example.com"],
     "formats":["markdown","html","metadata"]
-  }' --client Openclaw
+  }' --client ClaudeCode
 
   # Multiple URLs
   api contents --json '{
     "urls":["https://a.com","https://b.com"],
     "formats":["markdown"]
-  }' --client Openclaw
+  }' --client ClaudeCode
 
   # Save to file
   api contents --json '{
     "urls":["https://example.com"],
     "formats":["markdown"]
-  }' --client Openclaw | \
+  }' --client ClaudeCode | \
     jq -r '.[0].markdown' > output.md
 
   # With timeout
@@ -245,7 +245,7 @@ Examples:
     "urls":["https://example.com"],
     "formats":["markdown","metadata"],
     "crawl_timeout":30
-  }' --client Openclaw
+  }' --client ClaudeCode
 ```
 
 **Available contents parameters** (use `--schema` to see full schema):
@@ -363,7 +363,7 @@ console.log(response[0].metadata); // Structured metadata
 set -e
 
 # Capture result, check exit code
-if ! result=$(api search --json '{"query":"AI developments"}' --client Openclaw); then
+if ! result=$(api search --json '{"query":"AI developments"}' --client ClaudeCode); then
   echo "Search failed with code $?"
   exit 1
 fi
@@ -377,7 +377,7 @@ echo "$result" | jq .
 ```bash
 #!/usr/bin/env bash
 for i in {1..3}; do
-  if api search --json '{"query":"AI"}' --client Openclaw; then
+  if api search --json '{"query":"AI"}' --client ClaudeCode; then
     exit 0
   fi
   [ $i -lt 3 ] && sleep 5
@@ -390,9 +390,9 @@ exit 1
 
 ```bash
 #!/usr/bin/env bash
-ydc search --json '{"query":"AI"}' --client Openclaw &
-ydc search --json '{"query":"ML"}' --client Openclaw &
-ydc search --json '{"query":"LLM"}' --client Openclaw &
+ydc search --json '{"query":"AI"}' --client ClaudeCode &
+ydc search --json '{"query":"ML"}' --client ClaudeCode &
+ydc search --json '{"query":"LLM"}' --client ClaudeCode &
 wait
 ```
 
@@ -408,18 +408,18 @@ search=$(api search --json '{
   "count":5,
   "livecrawl":"web",
   "livecrawl_formats":"markdown"
-}' --client Openclaw)
+}' --client ClaudeCode)
 
 # Get comprehensive research with citations
 answer=$(api deep-search --json '{
   "query":"Summarize AI developments in 2026",
   "search_effort":"high"
-}' --client Openclaw)
+}' --client ClaudeCode)
 
 # Extract top result URL and fetch content
 url=$(echo "$search" | jq -r '.results.web[0].url')
 ydc contents --json "{\"urls\":[\"$url\"],\"formats\":[\"markdown\"]}" \
-  --client Openclaw | jq -r '.[0].markdown' > output.md
+  --client ClaudeCode | jq -r '.[0].markdown' > output.md
 ```
 
 ### Schema-Driven Agent
@@ -441,7 +441,7 @@ query=$(jq -n '{
 }')
 
 # Execute search
-ydc search --json "$query" --client Openclaw
+ydc search --json "$query" --client ClaudeCode
 ```
 
 ## Agent Skills Integration
@@ -462,10 +462,10 @@ The [youdotcom-cli skill](https://github.com/youdotcom-oss/agent-skills/tree/mai
 ### Compatible Agents
 
 Works with any bash-capable agent supporting Agent Skills:
-- **OpenClaw** - Open source bash agent
 - **Claude Code** - Anthropic's coding tool
-- **Codex** - OpenAI's CLI agent
 - **Cursor** - AI-powered code editor
+- **Droid** - Factory.ai agent
+- **Codex** - OpenAI's CLI agent
 - **Roo Code** - VS Code extension
 - And more...
 

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.2",
   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()
     }),
@@ -5222,7 +5225,7 @@ Output Format:
   Invalid args: Error message on stderr (exit 2)
 
 Examples:
-  ydc search --json '{"query":"AI developments"}' --client Openclaw
+  ydc search --json '{"query":"AI developments"}' --client ClaudeCode
   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

package/package.json

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

package/src/cli.ts

@@ -62,7 +62,7 @@ Output Format:
   Invalid args: Error message on stderr (exit 2)
 
 Examples:
-  ydc search --json '{"query":"AI developments"}' --client Openclaw
+  ydc search --json '{"query":"AI developments"}' --client ClaudeCode
   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

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