@youdotcom-oss/api 0.0.1

package/src/express/express.utils.ts

@@ -0,0 +1,113 @@
+import { EXPRESS_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 ExpressAgentApiResponse,
+  ExpressAgentApiResponseSchema,
+  type ExpressAgentInput,
+  type ExpressAgentMcpResponse,
+} from './express.schemas.ts'
+
+/**
+ * Checks response status and throws appropriate errors for agent API calls
+ */
+const agentThrowOnFailedStatus = async (response: Response) => {
+  const errorCode = response.status
+
+  const errorData = (await response.json()) as {
+    errors?: Array<{ detail?: string }>
+  }
+
+  if (errorCode === 400) {
+    throw new Error(`Bad Request:\n${JSON.stringify(errorData)}`)
+  } else if (errorCode === 401) {
+    throw new Error(
+      `Unauthorized: The Agent APIs require a valid You.com API key with agent access. Ensure your YDC_API_KEY has permissions for agent endpoints.`,
+    )
+  } else if (errorCode === 403) {
+    throw new Error(`Forbidden: You are not allowed to use the requested tool for this agent or tenant`)
+  } else if (errorCode === 429) {
+    throw new Error('Rate limited by You.com API. Please try again later.')
+  }
+  throw new Error(`Failed to call agent. Error code: ${errorCode}`)
+}
+
+export const callExpressAgent = async ({
+  YDC_API_KEY = process.env.YDC_API_KEY,
+  agentInput: { input, tools },
+  getUserAgent,
+}: {
+  agentInput: ExpressAgentInput
+  YDC_API_KEY?: string
+  getUserAgent: GetUserAgent
+}) => {
+  const requestBody: {
+    agent: string
+    input: string
+    stream: boolean
+    tools?: Array<{ type: 'web_search' }>
+  } = {
+    agent: 'express',
+    input,
+    stream: false, // Use non-streaming JSON response
+  }
+
+  // Only include tools if provided
+  if (tools) {
+    requestBody.tools = tools
+  }
+
+  const options = {
+    method: 'POST',
+    headers: new Headers({
+      Authorization: `Bearer ${YDC_API_KEY || ''}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'User-Agent': getUserAgent(),
+    }),
+    body: JSON.stringify(requestBody),
+  }
+
+  const response = await fetch(EXPRESS_API_URL, options)
+
+  if (!response.ok) {
+    await agentThrowOnFailedStatus(response)
+  }
+
+  // Parse JSON response directly
+  const jsonResponse = await response.json()
+
+  // Check for error field in response
+  checkResponseForErrors(jsonResponse)
+
+  // Validate API response schema (full response with all fields)
+  const apiResponse: ExpressAgentApiResponse = ExpressAgentApiResponseSchema.parse(jsonResponse)
+
+  // Find the answer (always present as message.answer, validated by Zod)
+  const answerItem = apiResponse.output.find((item) => item.type === 'message.answer')
+  if (!answerItem) {
+    throw new Error('Express API response missing required message.answer item')
+  }
+
+  // Find search results (optional, present when web_search tool is used)
+  const searchItem = apiResponse.output.find((item) => item.type === 'web_search.results')
+
+  // Transform API response to MCP output format (answer + optional search results, token efficient)
+  const mcpResponse: ExpressAgentMcpResponse = {
+    answer: answerItem.text,
+    agent: apiResponse.agent,
+  }
+
+  // Transform search results if present
+  if (searchItem && 'content' in searchItem && Array.isArray(searchItem.content)) {
+    mcpResponse.results = {
+      web: searchItem.content.map((item) => ({
+        url: item.url || item.citation_uri || '',
+        title: item.title || '',
+        snippet: item.snippet || '',
+      })),
+    }
+  }
+
+  return mcpResponse
+}

package/src/express/tests/express.utils.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, setDefaultTimeout, test } from 'bun:test'
+import { callExpressAgent } from '../express.utils.ts'
+
+const getUserAgent = () => 'API/test (You.com;TEST)'
+
+setDefaultTimeout(20_000)
+
+describe('callExpressAgent', () => {
+  test(
+    'returns answer only (WITHOUT web_search tools)',
+    async () => {
+      const result = await callExpressAgent({
+        agentInput: { input: 'What is machine learning?' },
+        getUserAgent,
+      })
+
+      // Verify MCP response structure
+      expect(result).toHaveProperty('answer')
+      expect(typeof result.answer).toBe('string')
+      expect(result.answer.length).toBeGreaterThan(0)
+
+      // Should NOT have results when web_search is not used
+      expect(result.results).toBeUndefined()
+
+      expect(result.agent).toBe('express')
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'returns answer and search results (WITH web_search tools)',
+    async () => {
+      const result = await callExpressAgent({
+        agentInput: {
+          input: 'Latest developments in quantum computing',
+          tools: [{ type: 'web_search' }],
+        },
+        getUserAgent,
+      })
+
+      // Verify MCP response has both answer and results
+      expect(result).toHaveProperty('answer')
+      expect(typeof result.answer).toBe('string')
+      expect(result.answer.length).toBeGreaterThan(0)
+
+      expect(result).toHaveProperty('results')
+      expect(result.results).toHaveProperty('web')
+      expect(Array.isArray(result.results?.web)).toBe(true)
+      expect(result.results?.web.length).toBeGreaterThan(0)
+
+      // Verify each search result has required fields
+      const firstResult = result.results?.web[0]
+      expect(firstResult).toHaveProperty('url')
+      expect(firstResult).toHaveProperty('title')
+      expect(firstResult).toHaveProperty('snippet')
+      expect(typeof firstResult?.url).toBe('string')
+      expect(typeof firstResult?.title).toBe('string')
+      expect(typeof firstResult?.snippet).toBe('string')
+      expect(firstResult?.url.length).toBeGreaterThan(0)
+      expect(firstResult?.title.length).toBeGreaterThan(0)
+
+      expect(result.agent).toBe('express')
+    },
+    { timeout: 30_000, retry: 2 },
+  )
+
+  test(
+    'works without optional parameters',
+    async () => {
+      const result = await callExpressAgent({
+        agentInput: { input: 'What is the capital of France?' },
+        getUserAgent,
+        // No progressToken or sendProgress provided
+      })
+
+      // Should work normally without progress tracking
+      expect(result).toHaveProperty('answer')
+      expect(result.answer.length).toBeGreaterThan(0)
+      expect(result.agent).toBe('express')
+    },
+    { retry: 2 },
+  )
+})

package/src/main.ts

@@ -0,0 +1,22 @@
+/**
+ * @youdotcom-oss/api - You.com API TS client utils
+ *
+ * This package provides lightweight API client functions and CLI tools
+ * for web search, AI answers, and content extraction.
+ *
+ * @public
+ */
+
+// 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'
+// 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/generate-error-report-link.ts'

package/src/search/search.schemas.ts

@@ -0,0 +1,110 @@
+import * as z from 'zod'
+
+export const SearchQuerySchema = z.object({
+  query: z.string().min(1, 'Query is required').describe('Search query (supports +, -, site:, filetype:, lang:)'),
+  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'),
+  country: z
+    .enum([
+      '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',
+      'PH',
+      'RU',
+      'SA',
+      'ZA',
+      'ES',
+      'SE',
+      'CH',
+      'TW',
+      'TR',
+      'GB',
+      'US',
+    ])
+    .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'),
+})
+
+export type SearchQuery = z.infer<typeof SearchQuerySchema>
+
+const WebResultSchema = z.object({
+  url: z.string().describe('URL'),
+  title: z.string().describe('Title'),
+  description: z.string().describe('Description'),
+  snippets: z.array(z.string()).describe('Content snippets'),
+  page_age: z.string().optional().describe('Publication timestamp'),
+  authors: z.array(z.string()).optional().describe('Authors'),
+  thumbnail_url: z.string().optional().describe('Thumbnail image URL'),
+  favicon_url: z.string().optional().describe('Favicon URL'),
+  contents: z
+    .object({
+      html: z.string().optional().describe('Full HTML content'),
+      markdown: z.string().optional().describe('Full Markdown content'),
+    })
+    .optional()
+    .describe('Live-crawled page content'),
+})
+
+const NewsResultSchema = z.object({
+  title: z.string().describe('Title'),
+  description: z.string().describe('Description'),
+  page_age: z.string().describe('Publication timestamp'),
+  url: z.string().describe('URL'),
+  thumbnail_url: z.string().optional().describe('Thumbnail image URL'),
+  contents: z
+    .object({
+      html: z.string().optional().describe('Full HTML content'),
+      markdown: z.string().optional().describe('Full Markdown content'),
+    })
+    .optional()
+    .describe('Live-crawled page content'),
+})
+
+export type NewsResult = z.infer<typeof NewsResultSchema>
+
+const MetadataSchema = z.object({
+  search_uuid: z.string().optional().describe('Unique search request ID'),
+  query: z.string().describe('Query'),
+  latency: z.number().describe('Latency in seconds'),
+})
+
+export const SearchResponseSchema = z.object({
+  results: z.object({
+    web: z.array(WebResultSchema).optional(),
+    news: z.array(NewsResultSchema).optional(),
+  }),
+  metadata: MetadataSchema.partial(),
+})
+
+export type SearchResponse = z.infer<typeof SearchResponseSchema>

package/src/search/search.utils.ts

@@ -0,0 +1,80 @@
+import { 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 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 },
+  getUserAgent,
+}: {
+  searchQuery: SearchQuery
+  YDC_API_KEY?: string
+  getUserAgent: GetUserAgent
+}) => {
+  const url = new URL(SEARCH_API_URL)
+
+  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}`)
+  }
+
+  url.search = searchParams.toString()
+
+  const options = {
+    method: 'GET',
+    headers: new Headers({
+      'X-API-Key': YDC_API_KEY || '',
+      'User-Agent': getUserAgent(),
+    }),
+  }
+
+  const response = await fetch(url, options)
+
+  if (!response.ok) {
+    const errorCode = response.status
+
+    if (errorCode === 429) {
+      throw new Error('Rate limited by You.com API. Please try again later.')
+    } else if (errorCode === 403) {
+      throw new Error('Forbidden. Please check your You.com API key.')
+    }
+
+    throw new Error(`Failed to perform search. Error code: ${errorCode}`)
+  }
+
+  const results = await response.json()
+
+  // Check for error field in 200 responses (e.g., API limit errors)
+  checkResponseForErrors(results)
+
+  const parsedResults = SearchResponseSchema.parse(results)
+
+  return parsedResults
+}

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

@@ -0,0 +1,135 @@
+import { describe, expect, test } from 'bun:test'
+import { fetchSearchResults } from '../search.utils.ts'
+
+const getUserAgent = () => 'API/test (You.com;TEST)'
+
+describe('fetchSearchResults', () => {
+  test(
+    'returns valid response structure for basic query',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: { query: 'latest stock news' },
+        getUserAgent,
+      })
+
+      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')
+
+      // search_uuid is optional but should be string if present
+      expect(result.metadata?.search_uuid).toBeDefined()
+      expect(typeof result.metadata?.search_uuid).toBe('string')
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'handles search with filters',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: {
+          query: 'javascript tutorial',
+          count: 3,
+          freshness: 'week',
+          country: 'US',
+        },
+        getUserAgent,
+      })
+
+      expect(result.results.web?.length).toBeLessThanOrEqual(3)
+      expect(result.metadata?.query).toContain('javascript tutorial')
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'validates response schema',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: { query: 'latest technology news' },
+        getUserAgent,
+      })
+
+      // Test that web results have required properties
+      // biome-ignore lint/style/noNonNullAssertion: Test
+      const webResult = result.results.web![0]
+
+      expect(webResult).toHaveProperty('url')
+      expect(webResult).toHaveProperty('title')
+      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 },
+  )
+
+  test(
+    'handles livecrawl parameters',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: {
+          query: 'python tutorial',
+          count: 2,
+          livecrawl: 'web',
+          livecrawl_formats: 'markdown',
+        },
+        getUserAgent,
+      })
+
+      expect(result.results.web?.length).toBeLessThanOrEqual(2)
+      // Livecrawl should return contents field (fails naturally if not present)
+      expect(result.results.web?.[0]).toHaveProperty('contents')
+      expect(result.results.web?.[0]?.contents).toHaveProperty('markdown')
+      expect(typeof result.results.web?.[0]?.contents?.markdown).toBe('string')
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'handles freshness date ranges',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: {
+          query: 'AI news',
+          freshness: '2024-01-01to2024-12-31',
+          count: 3,
+        },
+        getUserAgent,
+      })
+
+      expect(result).toHaveProperty('results')
+      expect(result.metadata?.query).toContain('AI news')
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'handles count greater than 20',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: {
+          query: 'machine learning',
+          count: 50,
+        },
+        getUserAgent,
+      })
+
+      expect(result.results.web?.length).toBeGreaterThan(0)
+      expect(result.results.web?.length).toBeLessThanOrEqual(50)
+    },
+    { retry: 2 },
+  )
+})

package/src/shared/api.constants.ts

@@ -0,0 +1,10 @@
+/**
+ * You.com API endpoints
+ *
+ * These constants define the base URLs for You.com's APIs.
+ * Exported for use in tests and external packages.
+ */
+
+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 CONTENTS_API_URL = 'https://ydc-index.io/v1/contents'

package/src/shared/api.types.ts

@@ -0,0 +1 @@
+export type GetUserAgent = () => string

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

@@ -0,0 +1,13 @@
+/**
+ * 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
+ */
+export const checkResponseForErrors = (responseData: unknown) => {
+  if (typeof responseData === 'object' && responseData !== null && 'error' in responseData) {
+    const errorMessage =
+      typeof responseData.error === 'string' ? responseData.error : JSON.stringify(responseData.error)
+    throw new Error(`You.com API Error: ${errorMessage}`)
+  }
+  return responseData
+}

package/src/shared/generate-error-report-link.ts

@@ -0,0 +1,35 @@
+/**
+ * Generates a mailto link for error reporting with pre-filled context
+ * Used by tool error handlers to provide easy error reporting
+ */
+export const generateErrorReportLink = ({
+  errorMessage,
+  tool,
+  clientInfo,
+}: {
+  errorMessage: string
+  tool: string
+  clientInfo: string
+}): string => {
+  const subject = `API Issue ${clientInfo}`
+  const body = `Client: ${clientInfo}
+Tool: ${tool}
+
+Error Message:
+${errorMessage}
+
+Steps to Reproduce:
+1.
+2.
+3.
+
+Additional Context:
+`
+
+  const params = new URLSearchParams({
+    subject,
+    body,
+  })
+
+  return `mailto:support@you.com?${params.toString()}`
+}

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

@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'bun:test'
+import { checkResponseForErrors } from '../check-response-for-errors.ts'
+
+describe('checkResponseForErrors', () => {
+  test('returns response data when no error field present', () => {
+    const responseData = { results: { web: [] }, metadata: {} }
+    const result = checkResponseForErrors(responseData)
+    expect(result).toEqual(responseData)
+  })
+
+  test('throws when error field is a string', () => {
+    const responseData = { error: 'API limit exceeded' }
+    expect(() => checkResponseForErrors(responseData)).toThrow('You.com API Error: API limit exceeded')
+  })
+
+  test('throws when error field is an object', () => {
+    const responseData = { error: { message: 'Invalid request', code: 400 } }
+    expect(() => checkResponseForErrors(responseData)).toThrow('You.com API Error:')
+  })
+
+  test('returns primitive values unchanged', () => {
+    expect(checkResponseForErrors('test')).toBe('test')
+    expect(checkResponseForErrors(123)).toBe(123)
+    expect(checkResponseForErrors(null)).toBe(null)
+  })
+
+  test('returns arrays unchanged', () => {
+    const arr = [1, 2, 3]
+    expect(checkResponseForErrors(arr)).toEqual(arr)
+  })
+})