@youdotcom-oss/api 0.1.0 → 0.2.0

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

package/src/shared/command-runner.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared command infrastructure for CLI commands
+ * Handles flag parsing, validation, and execution
+ *
+ * @internal
+ */
+
+import { parseArgs } from 'node:util'
+import * as z from 'zod'
+import type { GetUserAgent } from './api.types.ts'
+import type { DryRunResult } from './dry-run-utils.ts'
+import { useGetUserAgent } from './use-get-user-agents.ts'
+
+/**
+ * Configuration for a command
+ *
+ * @typeParam TInput - Zod-inferred input type
+ * @typeParam TOutput - Command output type
+ */
+export type CommandConfig<TInput, TOutput> = {
+  schema: z.ZodType<TInput>
+  handler: (params: { input: TInput; YDC_API_KEY: string; getUserAgent: GetUserAgent }) => Promise<TOutput>
+  dryRunHandler?: (params: { input: TInput; YDC_API_KEY: string; getUserAgent: GetUserAgent }) => DryRunResult
+}
+
+/**
+ * Run a command with standardized flag parsing and validation
+ * Handles --schema, --json, --api-key, --client, and --dry-run flags
+ *
+ * @param args - Command line arguments
+ * @param config - Command configuration with schema and handler
+ *
+ * @internal
+ */
+export const runCommand = async <TInput, TOutput>(args: string[], config: CommandConfig<TInput, TOutput>) => {
+  // Handle --schema flag
+  if (args.includes('--schema')) {
+    console.log(JSON.stringify(z.toJSONSchema(config.schema)))
+    process.exit(0)
+  }
+
+  // Parse flags with Node's built-in parseArgs
+  const { values } = parseArgs({
+    args,
+    options: {
+      json: { type: 'string' },
+      'api-key': { type: 'string' },
+      client: { type: 'string' },
+      'dry-run': { type: 'boolean' },
+    },
+  })
+
+  // --json is required
+  if (!values.json) {
+    throw new Error('--json flag is required')
+  }
+
+  // Parse JSON input
+  const input = JSON.parse(values.json)
+  const apiKey = values['api-key']
+  const client = values.client || process.env.YDC_CLIENT
+
+  // Get API key from options or environment
+  const YDC_API_KEY = apiKey || process.env.YDC_API_KEY
+  if (!YDC_API_KEY) {
+    throw new Error('YDC_API_KEY environment variable is required')
+  }
+
+  // Validate with schema
+  const validatedInput = config.schema.parse(input)
+
+  // Create getUserAgent function
+  const getUserAgent = useGetUserAgent(client)
+
+  // Handle --dry-run flag
+  if (values['dry-run'] && config.dryRunHandler) {
+    const dryRunResult = config.dryRunHandler({
+      input: validatedInput,
+      YDC_API_KEY,
+      getUserAgent,
+    })
+    console.log(JSON.stringify(dryRunResult))
+    return
+  }
+
+  // Execute handler
+  const response = await config.handler({
+    input: validatedInput,
+    YDC_API_KEY,
+    getUserAgent,
+  })
+
+  // Output response to stdout (success)
+  console.log(JSON.stringify(response))
+}

package/src/shared/dry-run-utils.ts

@@ -0,0 +1,141 @@
+/**
+ * Dry-run utilities for testing request construction without API calls
+ * These functions build request details (URL, headers, body) that can be inspected
+ * without making actual API calls.
+ *
+ * @public
+ */
+
+import type { ContentsQuery } from '../contents/contents.schemas.ts'
+import type { DeepSearchQuery } from '../deep-search/deep-search.schemas.ts'
+import type { SearchQuery } from '../search/search.schemas.ts'
+import { CONTENTS_API_URL, DEEP_SEARCH_API_URL, SEARCH_API_URL } from './api.constants.ts'
+import type { GetUserAgent } from './api.types.ts'
+
+/**
+ * Result structure for dry-run request inspection
+ *
+ * @public
+ */
+export type DryRunResult = {
+  url: string
+  method: 'GET' | 'POST'
+  headers: Record<string, string>
+  body?: string
+  queryParams?: Record<string, string>
+}
+
+/**
+ * Build search request details without making API call
+ * Useful for testing and debugging query construction
+ *
+ * @param params - Search query parameters
+ * @returns Request details including URL, headers, and query params
+ *
+ * @public
+ */
+export const buildSearchRequest = ({
+  searchQuery,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  searchQuery: SearchQuery
+  YDC_API_KEY: string
+  getUserAgent: GetUserAgent
+}): DryRunResult => {
+  // Convert all search query params to query string parameters
+  const queryParams: Record<string, string> = {}
+
+  for (const [name, value] of Object.entries(searchQuery)) {
+    if (value !== undefined && value !== null) {
+      queryParams[name] = `${value}`
+    }
+  }
+
+  return {
+    url: SEARCH_API_URL,
+    method: 'GET',
+    headers: {
+      'X-API-Key': YDC_API_KEY,
+      'User-Agent': getUserAgent(),
+    },
+    queryParams,
+  }
+}
+
+/**
+ * Build contents request details without making API call
+ * Useful for testing and debugging POST body construction
+ *
+ * @param params - Contents query parameters
+ * @returns Request details including URL, headers, and POST body
+ *
+ * @public
+ */
+export const buildContentsRequest = ({
+  contentsQuery: { urls, formats, format, crawl_timeout },
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  contentsQuery: ContentsQuery
+  YDC_API_KEY: string
+  getUserAgent: GetUserAgent
+}): DryRunResult => {
+  // Handle backward compatibility: prefer formats array, fallback to format string, default to ['markdown']
+  const requestFormats = formats || (format ? [format] : ['markdown'])
+
+  // Build request body
+  const requestBody: {
+    urls: string[]
+    formats: string[]
+    crawl_timeout?: number
+  } = {
+    urls,
+    formats: requestFormats,
+  }
+
+  if (crawl_timeout !== undefined) {
+    requestBody.crawl_timeout = crawl_timeout
+  }
+
+  return {
+    url: CONTENTS_API_URL,
+    method: 'POST',
+    headers: {
+      'X-API-Key': YDC_API_KEY,
+      'Content-Type': 'application/json',
+      'User-Agent': getUserAgent(),
+    },
+    body: JSON.stringify(requestBody),
+  }
+}
+
+/**
+ * Build deep-search request details without making API call
+ * Useful for testing and debugging POST body construction
+ *
+ * @param params - Deep-search query parameters
+ * @returns Request details including URL, headers, and POST body
+ *
+ * @public
+ */
+export const buildDeepSearchRequest = ({
+  deepSearchQuery,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  deepSearchQuery: DeepSearchQuery
+  YDC_API_KEY: string
+  getUserAgent: GetUserAgent
+}): DryRunResult => {
+  return {
+    url: DEEP_SEARCH_API_URL,
+    method: 'POST',
+    headers: {
+      'X-API-Key': YDC_API_KEY,
+      'Content-Type': 'application/json',
+      'User-Agent': getUserAgent(),
+    },
+    body: JSON.stringify(deepSearchQuery),
+  }
+}